跳至主要内容

REFERENCE

開發者參考

認證、API、SDK、Flow Agent 處理節點與參數取值的完整參考。

內建變數

Asgard Expression 與 Template 系統提供內建變數，讓您能夠在工作流程中動態存取對話資料、檔案資訊和頻道狀態。

  1. 內建變數清單​

    對話相關變數​

    prevMessage​

    • 型別：string
    • 說明：前一則使用者訊息內容
    • 用法：
    // Expression
    prevMessage || '無訊息'
    {{! Template }}
    {{#if prevMessage}}
      您說：{{prevMessage}}
    {{/if}}

    prevBlobs​

    • 型別：array<Blob>
    • 說明：前一則訊息的檔案清單
    • 用法：
    // Expression
    prevBlobs && prevBlobs.length > 0 ? `收到 ${prevBlobs.length} 個檔案` : '沒有檔案'
    {{! Template }}
    {{#if prevBlobs}}
      檔案清單：
      {{#each prevBlobs}}
        • {{fileName}} ({{size}} bytes)
      {{/each}}
    {{/if}}

    prevPayload​

    • 型別：object
    • 說明：前一則訊息的載荷資料
    • 用法：
    // Expression
    prevPayload && prevPayload.userAction
    {{! Template }}
    {{#if prevPayload}}
      載荷資料：{{{toJson prevPayload}}}
    {{/if}}

    prevError​

    • 型別：string
    • 說明：最近一次處理器錯誤訊息
    • 用法：
    // Expression
    prevError ? `發生錯誤：${prevError}` : '處理正常'
    {{! Template }}
    {{#if prevError}}
      錯誤訊息：{{prevError}}
    {{else}}
      處理成功
    {{/if}}

    頻道相關變數​

    customChannelId​

    • 型別：string
    • 說明：自定義頻道 ID
    • 用法：
    // Expression
    `頻道：${customChannelId}`
    {{! Template }}
    當前頻道：{{customChannelId}}

    customMessageId​

    • 型別：string
    • 說明：前一則訊息的客製化 ID（如果 client 無提供則為空字串）
    • 用法：
    // Expression
    customMessageId || '無自定義 ID'
    {{! Template }}
    {{#if customMessageId}}
      訊息 ID：{{customMessageId}}
    {{/if}}

  2. Blob 物件結構​

    interface Blob {
      blobId: number; // Blob 檔案的識別 ID
      fileType: FileType; // 檔案類型
      fileName?: string; // 原始檔名（可選）
      size: number; // 檔案大小（bytes）
      mime: string; // MIME 類型
    }
     
    type FileType = 'BINARY' | 'IMAGE' | 'VIDEO' | 'AUDIO' | 'DOCUMENT';

  3. 變數存取方式​

    安全存取模式​

    Expression 模式

    // 檢查變數存在性
    prevMessage && prevMessage.length > 0 ? prevMessage : '無訊息'
     
    // 使用邏輯運算符
    prevMessage || '預設訊息'
     
    // 安全存取陣列
    prevBlobs && prevBlobs[0] && prevBlobs[0].fileName
     
    // 檢查物件屬性
    prevPayload && 'property' in prevPayload ? prevPayload.property : '預設值'

    Template 模式

    {{#if prevMessage}}
      有訊息：{{prevMessage}}
    {{else}}
      無訊息
    {{/if}}
     
    {{#each prevBlobs}}
      檔案
      {{@index}}:
      {{fileName}}
    {{/each}}

  4. 實用範例​

    對話狀態檢查​

    // Expression：完整狀態檢查
    (() => {
      let status = [];
     
      if (prevMessage) {
        status.push(`訊息：${prevMessage.substring(0, 50)}...`);
      }
     
      if (prevBlobs && prevBlobs.length > 0) {
        status.push(`檔案：${prevBlobs.length} 個`);
      }
     
      if (prevError) {
        status.push(`錯誤：${prevError}`);
      }
     
      return status.length > 0 ? status.join(' | ') : '無狀態';
    })()
    {{! Template：狀態報告 }}
    • 對話狀態
     
    {{#if prevMessage}}
      • 最後訊息：{{prevMessage}}
    {{else}}
      • 尚未收到訊息
    {{/if}}
     
    {{#if prevBlobs}}
      • 檔案資訊：
      {{#each prevBlobs}}
        • {{fileName}} ({{fileType}}, {{size}} bytes)
      {{/each}}
    {{else}}
      • 沒有附件
    {{/if}}
     
    {{#if prevError}}
      • 錯誤：{{prevError}}
    {{else}}
      • 運作正常
    {{/if}}
     
    • 頻道：{{customChannelId}}

    檔案處理範例​

    // Expression：檔案分類統計
    (() => {
      if (!prevBlobs || prevBlobs.length === 0) {
        return '沒有檔案';
      }
     
      const stats = {};
      prevBlobs.forEach(blob => {
        stats[blob.fileType] = (stats[blob.fileType] || 0) + 1;
      });
     
      return Object.entries(stats)
        .map(([type, count]) => `${type}: ${count}`)
        .join(', ');
    })()
    {{! Template：檔案詳細資訊 }}
    {{#if prevBlobs}}
      • 檔案詳情：
      {{#each prevBlobs}}
        {{@index}}.
        {{fileName}}
        • 類型：{{fileType}}
        • 大小：{{size}} bytes
        • MIME：{{mime}}
        • ID：{{blobId}}
      {{/each}}
    {{/if}}

  5. 常見問題​

    Q: 如何檢查變數是否存在？

    // Expression
    typeof prevMessage !== 'undefined' && prevMessage !== null
     
    // 同時檢查 undefined 和 null
    prevMessage != null
    {{! Template }}
    {{#if prevMessage}}
      變數存在
    {{/if}}

    Q: 如何處理空陣列？

    // Expression
    prevBlobs && Array.isArray(prevBlobs) && prevBlobs.length > 0
    {{! Template }}
    {{#if prevBlobs}}
      {{#if prevBlobs.length}}
        有檔案
      {{/if}}
    {{/if}}

    Q: 如何安全存取檔案屬性？

    // Expression
    prevBlobs && prevBlobs[0] && prevBlobs[0].fileName
    {{! Template }}
    {{#if prevBlobs}}
      {{#each prevBlobs}}
        {{#if fileName}}
          檔名：{{fileName}}
        {{/if}}
      {{/each}}
    {{/if}}

    Q: 如何處理載荷資料？

    // Expression：安全存取載荷屬性
    prevPayload && typeof prevPayload === 'object' && 'action' in prevPayload ? prevPayload.action : '無動作'
    {{! Template：顯示載荷內容 }}
    {{#if prevPayload}}
      載荷內容：{{{toJson prevPayload}}}
    {{/if}}

    透過正確使用這些內建變數，您可以建立更智能和個人化的對話體驗。

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們