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

# 广告活动

> 创建、读取和更新没有关联帖子的广告活动，例如搜索广告活动。

活动是一种不以您的某条帖子为起点的广告。它适用于搜索广告等格式：您设置预算、出价策略和定位，由网络生成广告。

如需推广您已发布的帖子，请改用 [推广帖子](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md)。

> [!NOTE]
>
> Google 接受广告活动。有关 Google 的特定内容，请参阅 [Google 搜索广告活动](https://www.ayrshare.com/docs/apis/ads/google/search-campaigns.md) 和 [Google Performance Max 广告活动](https://www.ayrshare.com/docs/apis/ads/google/performance-max-campaigns.md)。其他网络会以 `code: 101` 拒绝广告活动请求，`details` 会说明原因。例如在 Facebook 上，它会显示 `campaignCreation is not supported on facebook.`

## 端点

| 方法 | 路径 | 作用 |
| - | - | - |
| `POST` | `/ads/{platform}/campaigns` | 创建活动 |
| `GET` | `/ads/{platform}/campaigns/{id}` | 获取单个活动 |
| `PUT` | `/ads/{platform}/campaigns/{id}` | 修改单个活动 |

`{platform}` 是广告网络。`{id}` 是创建活动时返回的活动 ID。您只能读取和修改由同一用户 Profile 通过 Ayrshare 创建的活动。

## 请求头参数

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

**Idempotency-Key** `string` *required*

创建活动时必填。每创建一个新活动，请发送一个新的唯一值，例如 UUID。如果使用相同的键重复请求，Ayrshare 会返回首次的响应（标记为 `idempotentReplayed: true`），且不会创建任何新内容。您也可以改为在请求体中以 `idempotencyKey` 发送该键。如果两者都发送，它们必须一致。

## 创建活动

`POST /ads/{platform}/campaigns`

除非您发送 `status: "active"`，否则新活动以 `paused` 状态开始，因此在您选择启动之前不会产生任何支出。

**accountId** `string` *required*

要在其中创建活动的广告账户。

**name** `string` *required*

活动名称，1 到 255 个字符。

**type** `string` *required*

活动类型：`search` 或 `performanceMax`。每个网络只支持部分类型。网络不支持的类型会返回 `code: 101`，并列出受支持的类型。

**budget** `object` *required*

**属性**

**amount** `number` *required*

每天的支出金额，最多保留两位小数。

**type** `string` *required*

`daily`。

**currency** `string`

ISO 4217 代码，例如 `USD`。默认为广告账户的货币。仅部分网络接受此字段。

**bidding** `object` *required*

**属性**

**strategy** `string` *required*

`maximizeConversions`、`maximizeConversionValue`、`targetCpa`、`targetRoas`、`maximizeClicks` 或 `manualCpc`。每个网络只支持部分策略。

**targetCpa** `number`

目标单次操作费用。使用 `targetCpa` 时必填，使用其他任何策略时均不接受。

**targetRoas** `number`

目标广告支出回报率，例如 `3.5` 表示 350%。使用 `targetRoas` 时必填，使用其他任何策略时均不接受。

**euPoliticalAdvertising** `boolean` *required*

该活动是否属于欧盟境内的政治广告。您必须始终发送此字段。Ayrshare 绝不会替您填写。

**schedule** `object`

**属性**

**start** `string`

开始时间：ISO 日期（`2026-11-01`），或带 `Z` 或时区偏移的 ISO 日期时间（`2026-11-01T09:00:00Z`）。默认为当前时间。

**end** `string`

结束时间，格式与 `start` 相同。必须晚于 `start`；如果省略 `start`，则必须晚于当前时间。省略此字段则活动无结束日期。按整天排期的网络（例如 Google）也接受与 `start` 同一天的 `end`，用于为期一天的活动。

**targeting** `object`

每个网络只支持部分定位选项。网络不支持的字段会返回 `code: 101`。

**属性**

**locations** `string[]`

网络自身的地区 ID。

**languages** `string[]`

网络自身的语言 ID。

**status** `string` (default: paused)

`active` 或 `paused`。

**platformOptions** `object`

仅适用于单个网络的选项，放在该网络的名称下，例如 `{ "facebook": { ... } }`。针对任何其他网络的选项会返回 `code: 101`。

```bash cURL theme={"system"}
curl \
-H "Authorization: Bearer API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10" \
-X POST https://api.ayrshare.com/api/ads/google/campaigns \
-d '{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}'
```

```javascript JavaScript theme={"system"}
const API_KEY = "API_KEY";

fetch("https://api.ayrshare.com/api/ads/google/campaigns", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
  },
  body: JSON.stringify({
    "accountId": "123-456-7890",
    "name": "Spring search",
    "type": "search",
    "budget": { "amount": 20, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/spring",
        "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
      }
    }
  })
})
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);
```

```python Python theme={"system"}
import requests

headers = {
    "Authorization": "Bearer API_KEY",
    "Idempotency-Key": "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10",
}

payload = {
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": False,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}

r = requests.post("https://api.ayrshare.com/api/ads/google/campaigns", headers=headers, json=payload)

print(r.json())
```

```php PHP theme={"system"}
<?php
$payload = <<<'JSON'
{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}
JSON;

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.ayrshare.com/api/ads/google/campaigns",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10"
    ],
    CURLOPT_POSTFIELDS => $payload
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error: " . $err;
} else {
    echo $response;
}
?>
```

```csharp C# theme={"system"}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer API_KEY");
        client.DefaultRequestHeaders.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10");

        var payload = """
            {
              "accountId": "123-456-7890",
              "name": "Spring search",
              "type": "search",
              "budget": { "amount": 20, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/spring",
                  "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
                }
              }
            }
            """;

        var response = await client.PostAsync(
            "https://api.ayrshare.com/api/ads/google/campaigns",
            new StringContent(payload, Encoding.UTF8, "application/json"));
        var content = await response.Content.ReadAsStringAsync();

        Console.WriteLine(content);
    }
}
```

```go Go theme={"system"}
package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := `{
  "accountId": "123-456-7890",
  "name": "Spring search",
  "type": "search",
  "budget": { "amount": 20, "type": "daily" },
  "bidding": { "strategy": "maximizeClicks" },
  "euPoliticalAdvertising": false,
  "platformOptions": {
    "google": {
      "finalUrl": "https://example.com/spring",
      "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
      "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
      "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
    }
  }
}`

    req, _ := http.NewRequest("POST", "https://api.ayrshare.com/api/ads/google/campaigns", strings.NewReader(payload))
    req.Header.Add("Authorization", "Bearer API_KEY")
    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

```java Java theme={"system"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class CreateCampaign {
    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "accountId": "123-456-7890",
              "name": "Spring search",
              "type": "search",
              "budget": { "amount": 20, "type": "daily" },
              "bidding": { "strategy": "maximizeClicks" },
              "euPoliticalAdvertising": false,
              "platformOptions": {
                "google": {
                  "finalUrl": "https://example.com/spring",
                  "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
                  "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
                  "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
                }
              }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.ayrshare.com/api/ads/google/campaigns"))
            .header("Authorization", "Bearer API_KEY")
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10")
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
```

```ruby Ruby theme={"system"}
require 'net/http'
require 'uri'

uri = URI.parse('https://api.ayrshare.com/api/ads/google/campaigns')

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer API_KEY'
request['Content-Type'] = 'application/json'
request['Idempotency-Key'] = '6f1c2d4e-0b7a-4c55-9a3e-2f8d1b7c9e10'
request.body = <<~JSON
  {
    "accountId": "123-456-7890",
    "name": "Spring search",
    "type": "search",
    "budget": { "amount": 20, "type": "daily" },
    "bidding": { "strategy": "maximizeClicks" },
    "euPoliticalAdvertising": false,
    "platformOptions": {
      "google": {
        "finalUrl": "https://example.com/spring",
        "headlines": ["Spring sale", "Shoes 30% off", "Free returns"],
        "descriptions": ["Every shoe 30% off this week.", "Free returns on every order."],
        "keywords": [{ "text": "running shoes", "matchType": "phrase" }]
      }
    }
  }
JSON

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body
```

创建成功时会返回 `status: "success"`、`campaignId`，以及以 `campaignStatus` 表示的活动自身状态（`active` 或 `paused`）。获取和更新的响应方式相同。

## 获取活动

`GET /ads/{platform}/campaigns/{id}`

返回网络所报告的活动信息。不属于您或不存在的活动会返回 `code: 400`。

## 更新活动

`PUT /ads/{platform}/campaigns/{id}`

请至少发送以下字段之一。创建活动后，您无法更改 `type`、`accountId` 或 `euPoliticalAdvertising`。

**name** `string`

新的活动名称。

**status** `string`

`active` 或 `paused`。当 Ayrshare 已暂停该网络上的广告时，仅发送 `status: "paused"` 的请求不会被阻止。但它仍需要已关联的网络，并且如果网络本身宕机，请求仍可能失败。

**budget** `object`

`{ "amount": number }`：新的每日支出金额。

**schedule** `object`

`{ "end": string }`：新的结束日期，格式与 `schedule.start` 相同。必须晚于活动的开始时间。按整天排期的网络（例如 Google）也接受与开始日期相同的日期。

## 错误

以下错误带有 Ayrshare `code`：

| 错误码 | 触发情况 |
| - | - |
| `101` | 请求无效、网络不支持活动或此活动类型，或缺少幂等键。`details` 会说明具体原因。Ayrshare 会在确认网络已关联之后才检查该键，因此未关联的 Profile 会先收到 "not linked"（未关联）错误。 |
| `400` | 该活动不属于您或不存在。 |
| `424` | 此网络上的广告暂时不可用。 |

创建请求也可能返回以下 HTTP 状态之一。其响应体不含 `code`，只有 `{ "action": "createAdCampaign", "status": "error", "message": "..." }`：

| HTTP 状态 | 触发情况 |
| - | - |
| `409` | 该幂等键已用于另一个不同的请求，或使用此键的请求仍在处理中。请勿使用新键重试。请先检查广告账户。 |
| `503` | Ayrshare 无法安全地预留该幂等键，因此未创建任何内容。请稍后使用相同的键重试。 |


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