Skip to main content
GraphQL API 透過單一端點提供 Ayrshare REST 功能中受支援的子集。每個公開的欄位都會呼叫與其 REST 對應項相同的底層控制器，因此驗證、權限、配額與回應資料皆遵循 REST 的行為。REST 仍是涵蓋範圍更廣的 API；請使用 schema 或 Explorer 確認 GraphQL 確切支援哪些操作。 GraphQL 帶來的好處是，你可以在一次請求中取得多項資料，並直接從 schema 本身探索目前支援的 GraphQL 功能，而不必逐頁閱讀文件。schema 描述了每個支援的請求欄位，以及結構化回應中可用的型別化選取欄位；以 JSON 傳回 REST 回應封包的操作則會保留完整的內容。
如同任何 GraphQL 端點，請傳送 POST，並在 JSON body 中包含 query。GET 與 DELETE 會傳回 405 Method Not Allowed。在 GraphQL 規範中，透過 GET 查詢是選用功能，此處不支援。

​
你的第一個查詢

回應與 REST history 端點傳回的 JSON 封包相同，只是包在 GraphQL 的 data 欄位中：

​
一次取得多項資料

選擇 GraphQL 的理由就是像這樣的請求，若使用 REST 則需要四次呼叫：
一次往返即可取得全部四項結果。請注意，這是四個根操作欄位，在計費上也算作四次 API 呼叫，而不是一次。選取巢狀的回應欄位不會增加呼叫次數，請參閱限制與計費。

​
驗證

與 REST 相同。將你的 API Key 作為 bearer token 傳送：
如果你的帳號使用 User Profiles，提供 profileKey 的操作可以透過以下任一方式選擇 profile：
  • 傳送 Profile-Key 作為整個請求的預設值。
  • 在個別欄位上傳入 profileKey 以覆寫該預設值，讓一次請求可以操作多個 profile。
兩者同時存在時，以欄位引數為準。帳號層級或僅限主要帳號的欄位不提供 profileKey，且可能會拒絕 Profile-Key header；例如，createProfile 必須使用主要 API Key，且不能帶有該 header。請查看每個欄位的 schema 定義以了解其適用範圍，並參閱管理多個使用者了解 profile key 的運作方式。

​
不必寫程式即可試用

GraphQL Explorer 是一個可瀏覽目前 schema 的互動式工具。它會列出每個可用的 GraphQL 操作及其引數與說明，在你輸入時自動完成，並可針對你的帳號執行查詢。 瀏覽 schema 不需要 API Key，因為 schema 是公開的，就像這份文件一樣。但執行查詢則需要 API Key，因為每個操作都會經過與 REST 相同的驗證。

​
該使用 GraphQL 還是 REST？

REST 仍是主要介面，我們大部分的文件、SDK 與整合都是以它為基礎建構的。在以下情況可以選擇 GraphQL：
  • 你需要多項彼此無關的資料，並希望在一次往返中取得。
  • 你需要機器可讀的操作名稱、引數、輸入物件、列舉與型別化的回應選取欄位。大多數回應仍為 JSON，以保留完整的 REST 回應封包；createPost 目前會傳回型別化的 PostResult。
  • 你正在探索 API，想了解有哪些功能，而不必在文件頁面之間切換。
在以下情況請繼續使用 REST：
  • 你要上傳檔案。媒體位元組無法透過 GraphQL 請求傳送，支援的做法請參閱上傳媒體。
  • 你使用的是我們的SDK 或無程式碼整合，這些都使用 REST。
  • 你希望依賴項目越少越好。REST 呼叫只需要一個 HTTP 用戶端。
兩種介面並行支援，你可以在同一個整合中自由混用。
  • 使用 API：尋找操作、引數型別與上傳媒體。
  • 錯誤：哪些失敗會改變 HTTP 狀態、為什麼失敗的操作仍會傳回 HTTP 200，以及如何處理部分成功。
  • 限制與計費：查詢大小上限與請求的計算方式。