GetMyBot 知識庫

資料來源與金鑰

從外部服務取得商品目錄或寫入訂單:保存服務網址與存取金鑰,並在反應中設定請求。

本頁內容

若商品資料在你的網站,機器人可以向網站查詢目錄,接單後也可把訂單送回網站。服務須提供 API,供程式交換資料。

在資料來源保存服務連接(連接器),包含 API 網址及請求設定;在金鑰保存憑證。反應中使用查詢資料來源或寫入資料來源動作。若服務已有現成連接方式,先查看整合。

連接器(資料來源)

在資料來源 → 連接器設定名稱、類型、基本 URL、憑證及標頭:

類型用途注意事項
REST一般 HTTP/JSON API填寫外部服務網址與憑證
OzmaDB自己的 OzmaDB/FunDB需要其 REST API 根網址;匿名 view 的讀取較易設定
IMAP已不支援新增舊連接仍在清單標示「不支援」,可照常刪除

檢查按鈕會送出測試請求,顯示狀態、延遲或錯誤,用來確認網址與金鑰。

憑證(金鑰)

在金鑰 → 憑證依外部服務文件選擇授權方式。資料加密儲存:

方法所需資料
API 金鑰金鑰及標頭名稱,預設 Authorization
Bearer 權杖Authorization: Bearer 的權杖
OAuth2(password)Token URL、Client ID/Secret、帳號、密碼、scope
OAuth2(refresh)Token URL、Client ID/Secret、refresh 權杖、scope

OAuth2 的暫時存取權杖由 GetMyBot 取得,過期或服務回傳 401 時自動更新。若服務簽發新 refresh 權杖,平台會保存。編輯時秘密欄位留空表示保留舊值。

在反應中讀寫資料

  • 查詢資料來源(ds_query):讀取資料並存入暫存 ctx。指定請求路徑、回應中清單的位置(JSONPath)及結果名稱。例如將商品存為 products,供動態按鈕或迴圈使用。
  • 寫入資料來源(ds_write):以 POST、PUT 或 DELETE 傳送 JSON 資料。

請求內容、重試與回應檢查

網路請求和寫入資料來源的 POST/PUT 內容可用JSON 樹建立。每個葉節點可選字串、數字、布林、JSON 或 null,並支援變數替換,因此數字不會變成文字,巢狀物件也不用手動處理跳脫:

{"customer":{"name":"{{param.name}}","phone":"{{user.phone}}"},"amount":4900,"paid":false}

舊版文字內容仍可使用;切換模式會顯示目前資料,不會丟棄輸入。

重試(retry_count)只在網路錯誤、429 和 5xx 時進行,其他 4xx 不重試。GET、HEAD、OPTIONS、PUT、DELETE 可重試;POST 和 PATCH 只有在你自行加入 Idempotency-Key、確認接收服務會排除重複操作時才重試。平台亦會傳送固定的步驟鍵,但單靠它不會啟用 POST/PATCH 重試,以免重複建立訂單。整合和 CRM 寫入若結果不明,平台不會自行重試;唯一例外是設定了自有 Idempotency-Key 的網路請求。

REST 連接器編輯器的檢查回應會使用保存的連接,向指定路徑和參數送出一次不含變數的 GET,顯示狀態、類型與最多 64 KB 內容。它不寫入資料。JSON 回應可作為解析回應的範例。

網路請求、資料來源讀寫、AI、Google Sheets、Google Drive、GetCourse 和 CRM 動作都支援解析回應。「動作結果」是處理後的標準結果,「完整回應」是處理前的內容。解析規則會一起套用;只要有一條失敗,就不寫入任何變數。

一次性請求可直接用網路請求,只需抓取網頁文字可用載入 URL,詳見動作。

OzmaDB 的命名檢視與資料表

先保存 OzmaDB 連接,在資料來源讀寫動作中選擇它並切換至 OzmaDB 模式。既有 HTTP 動作會保留原模式及參數;編輯器開啟期間明確切換模式時,HTTP 欄位會保留,Ozma 設定也可恢復。

讀取時,可手動填寫固定的Schema 和檢視(view)名稱,或按載入目錄。載入更多會取得後續頁面,並保留所選物件。載入參數與欄位會從中繼資料提供參數建議;各參數須填名稱、類型和值。無法讀取目錄或中繼資料時仍可手動輸入。

view 是可聯結資料表並計算欄位的已保存查詢,用於讀取;建立或更新記錄須選資料表 Entity。

讀取帶數字參數 team_id 的 usr.people_by_team:

{"connection":"ozma","ozma":{"schema":"usr","view":"people_by_team","args":{"team_id":{"type":"number","value":"42"}},"limit":100,"offset":0},"save_to_ctx":"people"}

結果會作為按欄名建立的物件陣列存入 ctx.people,例如 [{"id":7,"name":"Alex"}]。預設每頁 100、最多 500,offset 範圍 0–100000。分頁讀取時,應在檢視中設定穩定排序。

讀取預覽只讀取最多 20 列。參數須填具體值,不能使用事件變數;若需測試變數,先暫時換成測試值。寫入沒有預覽。

寫入時填Schema、Entity,選建立或更新,再設定有型別的欄位。更新須提供正的記錄 ID,也可取自先前動作:

{
  "connection":"ozma",
  "ozma":{
    "schema":"usr","entity":"person","operation":"update","id":"{{ctx.person_id}}",
    "fields":{
      "name":{"type":"string","value":"{{text}}"},
      "active":{"type":"boolean","value":"true"},
      "details":{"type":"json","value":"{\"tags\":[\"member\"]}"},
      "note":{"type":"null","value":""}
    }
  },
  "save_to_ctx":"saved_person"
}

可選擇把交易回應存入情境;第一筆 ID 為 ctx.saved_person.results[0].id。建立記錄時用 insert 且不填 id。建立時空的 fields 會使用 Entity 預設值;更新至少要有一個欄位。中繼資料建議不包含計算欄及禁止操作的欄位,最終權限與限制仍由 OzmaDB 檢查。

可用型別為 string、number、boolean、json、null。動作 JSON 中的 value 一律是字串,執行時才在變數替換後轉型。數字文字可保留精確寫法,string 不會被當作 JSON 語法;json 必須是有效 JSON 或含完整 JSON 的變數,格式錯誤會失敗。Schema、物件和欄位名稱都須固定填寫,不能使用變數。

寫入後若回應遺失,操作結果可能不明;重試前先到 OzmaDB 查驗資料。沒有已確認的去重機制時,自動重試不安全。明確的批次交易仍使用HTTP 請求模式。

從 JSON 擷取任意資料

兩種資料來源動作(包括 HTTP 模式)的解析回應都可從 result_path 或 Ozma 標準化後的動作結果,或處理前的完整回應擷取資料。主要結果鍵仍會保存,解析規則則另外寫入明確指定的 ctx 鍵。

讀取預覽後,列會自動出現在解析樹中;預覽本身不會啟用解析或修改動作。點擊欄位可建立命名變數;從所有記錄收集可把每列某欄收成清單,例如把 id 存為 ids。新規則會加到舊規則後,名稱自動取得不重複的後綴;可改名及複製變數寫法。

完整回應、第一筆、全部 ID提供常用選擇,後兩者只在範例含相應陣列時出現。寫入動作的新記錄 ID可加入必填 created_id,無須測試寫入。新解析預設使用完整回應,既有解析保留原來源;可手動切換。亦可貼入 JSON 範例,在進階設定修改路徑、模式及巢狀 JSON 字串解析。大樹只顯示部分內容。範例不會進入動作參數或流程分析;檢查解析只對範例執行純解析,不呼叫資料來源。

範例回應:

{"results":[{"id":9007199254740993}],"groups":[{"members":[{"name":"Alex","active":false}]},{"members":[{"name":"Sam","active":true}]}],"extra":"{\"status\":{\"ready\":false}}"}

在動作參數中加入:

{"response_parser":{"source":"raw","decode_json_strings":true,"rules":[{"path":"$.results[0].id","save_to_ctx":"created_id","mode":"value","required":true},{"path":"$.groups[*].members[*].name","save_to_ctx":"member_names","mode":"list"},{"path":"/extra/status/ready","save_to_ctx":"ready","mode":"value"}]}}

規則會精確保存 created_id、取得 member_names = ["Alex","Sam"] 並保存布林值 ready = false。後續更新動作可在記錄 ID 欄使用 {{ctx.created_id}}。可擷取字串、數字、布林、物件、陣列、null,甚至整個根物件 $;解析字串中的 JSON會在預覽樹中展開有效的巢狀 JSON。

支援 .name、經 JSON 跳脫的 ["a.b"]、正負索引([0]、[-1])、所有項目([*]、.*)、切片([1:3])及 RFC 6901 JSON Pointer。字面鍵 a/b 用 /a~1b,~ 編碼為 ~0,路徑 / 指向空鍵。不支援篩選器、表示式或腳本。

單一值模式遇到多個符合項會報錯;萬用字元路徑應用值清單。必填規則找不到值時報錯;非必填的缺失單值為 null,缺失清單為 [],預覽會區分「找到 null」和「未找到」。所有規則先算完才改變 ctx。限制:32 條規則、每條路徑 1024 位元組、輸入與輸出各 1 MiB、每條最多 1000 個符合項,並有限制深度和遍歷量。

Ozma 記錄 ID 與關聯標籤

**加入主要記錄 ID(mainId)與加入關聯值標籤(pun)**可分別啟用。include_main_id: true 保存每列 mainId;parse_pun: true 將有標籤的儲存格表示為 { "id": 42, "data": "標籤" }。若與既有 mainId 欄衝突,會明確報錯。兩項都不會修改完整原始回應。

讀取後可在進階解析設定中切換列資料或完整回應。已設定完整回應時會自動顯示對應範例;更改物件、參數或讀取旗標會清除過時的自動範例。樹立即可用,JSON 範例與JSON 回應編輯器按需展開;超出預覽限制時會自動顯示訊息並開啟編輯器。

在下一動作按變數替換,於先前動作群組找到 created_id,按 {{ctx.created_id}} 旁的插入,就能放到記錄 ID 或參數值欄的游標位置。清單只含目前區塊中更早的動作;重新命名、刪除或調整順序會立即更新清單。

搜尋目錄與物件中繼資料

新建 Ozma 讀取動作時,情境結果鍵位於物件設定之前,預設建議 ozma_rows;若與解析規則重名,會加入後綴。既有名稱及手動清空的欄位保持不變。讀取時結果鍵必填,寫入時可留空;讀取缺少鍵會在欄位旁顯示具體錯誤。

載入目錄每頁取得 50 個讀取檢視或寫入資料表;在目錄物件中可於整個遠端目錄搜尋 schema.name。搜尋不區分大小寫,按字面子字串比對,_ 和 % 都是普通字元。載入更多從伺服器回傳的位移繼續。切換搜尋或重試時,已選物件仍可見;即使目錄存取被拒,Schema 與名稱仍可手動填寫。

載入參數與欄位會顯示必填參數、關聯目標、欄位型別及主要資料表。其他中繼資料可展開未知欄位及以 JSON 字串編碼的物件、陣列。數值保持精確表示;資料過大或太深時會顯示預覽限制。查看中繼資料不會改變動作或解析規則。

Ozma 完整設定流程

Ozma 連接表單分開呈現名稱/類型、實例網址及已保存金鑰。其他 HTTP 標頭在空白時收起,有設定時展開。連接檢查結果顯示在按鈕旁;變更設定後舊結果會隱藏,舊設定的遲到回應不會證明新設定有效。

在動作中,連接與模式並列,結果鍵在表單開始處,所選 schema.view 或 schema.entity 顯示在物件設定上方。手動 Schema/名稱在手動輸入區,已選合法物件時收起,名稱空白、錯誤或存取拒絕時展開。參數及寫入欄位各以名稱、類型、值、刪除排列;中繼資料的必填提示維持可見,型別詳情可在類型與變數替換查看。

讀取參數集中管理分頁、主要 ID 及關聯標籤。預設值收起,非預設值及分頁錯誤會展開。檢查讀取先以表格展示標準化記錄,按需展開JSON 回應;空結果會提示檢查項目,精確數值會保留。標準化 JSON 與OzmaDB 完整回應可分開展開。

Ozma 解析區將快捷選擇、結果變數、進階選擇器、區域範例樹及檢查結果放在一起。既有 HTTP 動作保留原本的顯示及 parser 行為。其他中繼資料直接展開至欄位,不會多加一層根節點。

下一步