> ## 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.

# 廣告

> 透過 Ayrshare GraphQL API 管理推廣廣告，使用一組以廣告平台作為引數的操作。

廣告操作以廣告平台作為引數，因此同一個操作適用於 Ayrshare 支援的所有廣告平台。目前支援 `FACEBOOK` 與 `INSTAGRAM`。

每個操作都會呼叫對應的 [REST 廣告端點](/docs/apis/ads/overview)，並原封不動地傳回其回應。驗證與限制皆與 REST 相同。呼叫失敗時會傳回 GraphQL 錯誤：`extensions.status` 帶有 REST 狀態碼，若 REST 錯誤含有 Ayrshare 錯誤碼，則 `extensions.code` 會帶有該錯誤碼。請參閱[錯誤](/docs/apis/graphql/errors)。廣告操作需要 Ads 附加元件。若未啟用，每次呼叫都會傳回 `extensions.status` 為 `403`、`extensions.code` 為 `399` 的錯誤。

<h2 id="operations">
  操作
</h2>

| 操作 | 類型 | REST 端點 |
| - | - | - |
| `adAccounts` | Query | `GET /ads/{platform}/accounts` |
| `adTargetingSearch` | Query | `GET /ads/{platform}/interests`、`/regions` 或 `/cities` |
| `ads` | Query | `GET /ads/{platform}/ads` |
| `adHistory` | Query | `GET /ads/{platform}/history` |
| `updateAd` | Mutation | `PUT /ads/{platform}/ads` |

每個操作也都接受選用的 `profileKey`，以針對某個 User Profile（使用者設定檔）執行。所有操作都以 JSON 傳回 REST 回應，因此不需要選取欄位。

<h2 id="list-ad-accounts">
  列出廣告帳戶
</h2>

從這裡開始。凡是操作要求提供 `accountId` 時，請使用此回應中的 `accountId` 值。

```graphql theme={"system"}
query {
  adAccounts(platform: FACEBOOK, limit: 10)
}
```

<h2 id="search-targeting-options">
  搜尋目標設定選項
</h2>

`kind` 決定搜尋類型：`INTERESTS` 用於受眾目標設定，`REGIONS` 或 `CITIES` 用於地點。每種類型只接受各自的引數。例如，`countryCode` 與 `regionId` 僅適用於 `CITIES`，而 `INTERESTS` 需要 `search`。

```graphql theme={"system"}
query {
  adTargetingSearch(platform: INSTAGRAM, kind: INTERESTS, search: "running")
}
```

```graphql theme={"system"}
query {
  adTargetingSearch(platform: FACEBOOK, kind: CITIES, search: "Austin", countryCode: "US")
}
```

<h2 id="list-ads">
  列出廣告
</h2>

請至少傳入 `campaignId`、`accountId`、`adId`、`postId` 或 `socialPostId` 其中之一。`socialPostId` 是社群網路本身的貼文 id，適用於非透過 Ayrshare 發布的貼文。

```graphql theme={"system"}
query {
  ads(platform: FACEBOOK, accountId: "act_1234567890")
}
```

<h2 id="see-what-an-ad-has-cost">
  查看廣告的花費
</h2>

```graphql theme={"system"}
query {
  adHistory(platform: FACEBOOK, startDate: "2026-09-01", endDate: "2026-09-30")
}
```

<h2 id="pause-or-resume-an-ad">
  暫停或恢復廣告
</h2>

`updateAd` 會影響實際的廣告支出。`PAUSED` 會停止支出，`ACTIVE` 會恢復支出，而 `DELETED` 或 `ARCHIVED` 會停用廣告。相同的狀態也會套用到該廣告所屬的廣告集與活動，因此該廣告集或活動中的其他廣告也會隨之變更。

```graphql theme={"system"}
mutation {
  updateAd(platform: FACEBOOK, adId: "120210000000000000", status: PAUSED)
}
```

<Note>
  透過這些操作推廣貼文的功能即將推出。在此之前，請使用 `boostFacebookPost` 或 `instagramBoostPost`，或是 [Facebook](/docs/apis/ads/facebook/boost-post) 或 [Instagram](/docs/apis/ads/instagram/boost-post) 的 REST 推廣端點。
</Note>

各平台專屬的操作（例如 `facebookAdAccounts` 與 `instagramAds`）仍可正常使用，且維持不變。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.