> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL API 概觀

> 透過單一 GraphQL 端點查詢 Ayrshare 支援的社群媒體操作。

GraphQL API 透過單一端點提供 Ayrshare REST 功能中受支援的子集。每個公開的欄位都會呼叫與其 REST 對應項相同的底層控制器，因此驗證、權限、配額與回應資料皆遵循 REST 的行為。REST 仍是涵蓋範圍更廣的 API；請使用 schema 或 Explorer 確認 GraphQL 確切支援哪些操作。

GraphQL 帶來的好處是，你可以在一次請求中取得多項資料，並直接從 schema 本身探索目前支援的 GraphQL 功能，而不必逐頁閱讀文件。schema 描述了每個支援的請求欄位，以及結構化回應中可用的型別化選取欄位；以 `JSON` 傳回 REST 回應封包的操作則會保留完整的內容。

```
https://api.ayrshare.com/graphql
```

如同任何 GraphQL 端點，請傳送 `POST`，並在 JSON body 中包含 `query`。`GET` 與 `DELETE` 會傳回 `405 Method Not Allowed`。在 GraphQL 規範中，透過 `GET` 查詢是選用功能，此處不支援。

<h2 id="your-first-query">
  你的第一個查詢
</h2>

```bash theme={"system"}
curl -X POST https://api.ayrshare.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ postHistory(lastDays: 7) }"}'
```

回應與 [REST history 端點](/docs/apis/history/get-history)傳回的 JSON 封包相同，只是包在 GraphQL 的 `data` 欄位中：

```json theme={"system"}
{
  "data": {
    "postHistory": {
      "history": [
        { "id": "RkQ8uXg2jT7bNd1Wq0Ya", "status": "success", "post": "Hello world" }
      ],
      "refId": "9d2a7c41f0b8e6d35a1c",
      "count": 1,
      "lastUpdated": "2026-09-24T12:00:00.000Z",
      "nextUpdate": "2026-09-24T12:00:00.000Z"
    }
  }
}
```

<h2 id="asking-for-several-things-at-once">
  一次取得多項資料
</h2>

選擇 GraphQL 的理由就是像這樣的請求，若使用 REST 則需要四次呼叫：

```graphql theme={"system"}
{
  history: postHistory(lastDays: 7)
  accounts: user
  comments: comments(id: "abc123")
  analytics: socialAnalytics(platforms: [INSTAGRAM])
}
```

一次往返即可取得全部四項結果。請注意，這是**四個根操作欄位，在計費上也算作四次 API 呼叫**，而不是一次。選取巢狀的回應欄位不會增加呼叫次數，請參閱[限制與計費](/docs/apis/graphql/limits)。

<h2 id="authentication">
  驗證
</h2>

與 REST 相同。將你的 API Key 作為 bearer token 傳送：

```
Authorization: Bearer YOUR_API_KEY
```

如果你的帳號使用 User Profiles，提供 `profileKey` 的操作可以透過以下任一方式選擇 profile：

<ul class="custom-bullets">
  <li>傳送 <code>Profile-Key</code> 作為整個請求的預設值。</li>
  <li>在個別欄位上傳入 <code>profileKey</code> 以覆寫該預設值，讓一次請求可以操作多個 profile。</li>
</ul>

兩者同時存在時，以欄位引數為準。帳號層級或僅限主要帳號的欄位不提供 `profileKey`，且可能會拒絕 `Profile-Key` header；例如，`createProfile` 必須使用主要 API Key，且不能帶有該 header。請查看每個欄位的 schema 定義以了解其適用範圍，並參閱[管理多個使用者](/docs/multiple-users/business-plan-overview)了解 profile key 的運作方式。

<h2 id="try-it-without-writing-code">
  不必寫程式即可試用
</h2>

[GraphQL Explorer](https://app.ayrshare.com/graphql-explorer) 是一個可瀏覽目前 schema 的互動式工具。它會列出每個可用的 GraphQL 操作及其引數與說明，在你輸入時自動完成，並可針對你的帳號執行查詢。

瀏覽 schema 不需要 API Key，因為 schema 是公開的，就像這份文件一樣。但執行查詢則需要 API Key，因為每個操作都會經過與 REST 相同的驗證。

<h2 id="should-you-use-graphql-or-rest">
  該使用 GraphQL 還是 REST？
</h2>

REST 仍是主要介面，我們大部分的文件、[SDK](/docs/packages-guides/overview) 與整合都是以它為基礎建構的。在以下情況可以選擇 GraphQL：

<ul class="custom-bullets">
  <li>你需要多項彼此無關的資料，並希望在一次往返中取得。</li>
  <li>你需要機器可讀的操作名稱、引數、輸入物件、列舉與型別化的回應選取欄位。大多數回應仍為 <code>JSON</code>，以保留完整的 REST 回應封包；<code>createPost</code> 目前會傳回型別化的 <code>PostResult</code>。</li>
  <li>你正在探索 API，想了解有哪些功能，而不必在文件頁面之間切換。</li>
</ul>

在以下情況請繼續使用 REST：

<ul class="custom-bullets">
  <li>你要上傳檔案。媒體位元組無法透過 GraphQL 請求傳送，支援的做法請參閱<a href="/docs/apis/graphql/using-the-api#uploading-media">上傳媒體</a>。</li>
  <li>你使用的是我們的<a href="/docs/packages-guides/overview">SDK 或無程式碼整合</a>，這些都使用 REST。</li>
  <li>你希望依賴項目越少越好。REST 呼叫只需要一個 HTTP 用戶端。</li>
</ul>

兩種介面並行支援，你可以在同一個整合中自由混用。

<h2 id="read-next">
  延伸閱讀
</h2>

<ul class="custom-bullets">
  <li>[使用 API](/docs/apis/graphql/using-the-api)：尋找操作、引數型別與上傳媒體。</li>
  <li>[錯誤](/docs/apis/graphql/errors)：哪些失敗會改變 HTTP 狀態、為什麼失敗的操作仍會傳回 HTTP 200，以及如何處理部分成功。</li>
  <li>[限制與計費](/docs/apis/graphql/limits)：查詢大小上限與請求的計算方式。</li>
</ul>