> ## 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` 的错误。

## 操作

| 操作 | 类型 | REST 端点 |
| - | - | - |
| `adAccounts` | Query | `GET /ads/{platform}/accounts` |
| `adTargetingSearch` | Query | `GET /ads/{platform}/interests`, `/regions` or `/cities` |
| `ads` | Query | `GET /ads/{platform}/ads` |
| `adHistory` | Query | `GET /ads/{platform}/history` |
| `updateAd` | Mutation | `PUT /ads/{platform}/ads` |

每个操作还接受可选的 `profileKey`，用于对某个 User Profile（用户配置文件）执行操作。所有操作都以 JSON 形式返回 REST 响应，因此不接受字段选择。

## 列出广告账户

从这里开始。凡是操作需要 `accountId` 的地方，都使用响应中的 `accountId` 值。

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

## 搜索定向选项

`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")
}
```

## 列出广告

至少传入 `campaignId`、`accountId`、`adId`、`postId` 或 `socialPostId` 中的一个。`socialPostId` 是社交网络自身的帖子 ID，用于并非通过 Ayrshare 发布的帖子。

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

## 查看广告花费

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

## 暂停或恢复广告

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