> ## 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}` | キャンペーンを1件取得する |
| `PUT` | `/ads/{platform}/campaigns/{id}` | キャンペーンを1件変更する |

`{platform}` は広告ネットワークです。`{id}` はキャンペーン作成時に返されたキャンペーン ID です。取得・変更できるのは、同じユーザープロフィールで 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*

1日あたりの費用。小数点以下2桁まで指定できます。

**type** `string` *required*

`daily`。

**currency** `string`

`USD` などの ISO 4217 コード。デフォルトは広告アカウントの通貨です。一部のネットワークのみが受け付けます。

**bidding** `object` *required*

**プロパティ**

**strategy** `string` *required*

`maximizeConversions`、`maximizeConversionValue`、`targetCpa`、`targetRoas`、`maximizeClicks`、または `manualCpc`。各ネットワークが対応しているのは一部の戦略のみです。

**targetCpa** `number`

目標コンバージョン単価。`targetCpa` の場合は必須で、それ以外の戦略では受け付けられません。

**targetRoas** `number`

目標広告費用対効果。たとえば 350% の場合は `3.5` です。`targetRoas` の場合は必須で、それ以外の戦略では受け付けられません。

**euPoliticalAdvertising** `boolean` *required*

キャンペーンが EU における政治広告かどうか。常に送信する必要があります。Ayrshare が代わりに値を設定することはありません。

**schedule** `object`

**プロパティ**

**start** `string`

開始日時: ISO 日付(`2026-11-01`)、または `Z` かオフセット付きの ISO 日時(`2026-11-01T09:00:00Z`)。デフォルトは現在時刻です。

**end** `string`

終了日時。`start` と同じ形式です。`start` より後、または `start` を省略した場合は現在時刻より後である必要があります。終了日なしで実行する場合は省略してください。Google のように日単位でスケジュールするネットワークでは、1日だけのキャンペーンとして `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}`

以下のフィールドのうち少なくとも1つを送信してください。キャンペーンの作成後に `type`、`accountId`、`euPoliticalAdvertising` を変更することはできません。

**name** `string`

新しいキャンペーン名。

**status** `string`

`active` または `paused`。`status: "paused"` のみを送信するリクエストは、Ayrshare がそのネットワークの広告を一時停止している場合でもブロックされません。ただし、ネットワークがリンクされている必要があり、ネットワーク自体がダウンしている場合は失敗する可能性があります。

**budget** `object`

`{ "amount": number }`: 1日あたりの新しい費用。

**schedule** `object`

`{ "end": string }`: 新しい終了日。`schedule.start` と同じ形式です。キャンペーンの開始日時より後である必要があります。Google のように日単位でスケジュールするネットワークでは、開始日と同じ日も受け付けます。

## エラー

以下のエラーには Ayrshare の `code` が含まれます:

| コード | 発生条件 |
| - | - |
| `101` | リクエストが無効である、ネットワークがキャンペーンまたはこのキャンペーンの種類をサポートしていない、または冪等性キーがない。どれに該当するかは `details` に示されます。Ayrshare はネットワークがリンクされていることを確認した後にキーをチェックするため、リンクされていないプロフィールには先に "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.