Mutate

Google 広告スクリプトは、 Google Ads APIで利用可能な汎用的な変更をサポートしています。 GoogleAdsService.mutate から実行できるオペレーションのほとんどは、キャンペーンの作成や管理など、Google 広告スクリプトでも実行できます。

この機能を使用すると、Google Ads API の大部分にアクセスできるため、この機能を使用するには、Google Ads API の規則を基本的なレベルで理解しておくことが重要です。デベロッパートークンや承認など、Google 広告スクリプトで処理される多くの側面はスキップできますが、有効な変更リクエストを作成する必要があります。

このガイドに進む前に、Google Ads API REST インターフェースに関する基本的なリソースをいくつかご紹介します。

基本的な例

機能を示すために、キャンペーンの予算を作成する基本的な例を以下に示します。

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

の呼び出しでは、単一の MutateOperationを表す JSON オブジェクトが使用されます。AdsApp.mutateこのオブジェクト内で、実行するオペレーションの種類（この場合は campaignBudgetOperation ）を指定します。次に、create、remove、または update と updateMask の両方を指定します。create と update 内の特定のフィールドは、操作するリソースのタイプによって異なります。

オペレーションを作成する

有効なオペレーションを作成するには、いくつかの方法があります。キャンペーンの予算の例では、キャンペーンの予算の REST リファレンスドキュメントで有効なフィールドのリストを確認し、適切なフィールドに入力するか、スクリプトでカスタム JavaScript コードを作成して適切なオブジェクトを作成します。

または、キャンペーンの予算の [試す]機能を使用して、オペレーションを動的に作成することもできます。この機能を使用すると、追加するフィールドを選択してリクエスト本文を動的に作成できます。次に、生成された結果からオペレーションの内容を抽出し、オペレーションタイプを指定した後で mutate 呼び出しに追加します。

オペレーションタイプ

作成

オペレーションで create を指定し、作成するリソースのオブジェクト表現を渡します。

create オペレーションの例については、前述のスニペットをご覧ください。

削除

オペレーションで remove を指定し、削除するリソースのリソース名を渡します。例:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

エンティティのリソース名がわからない場合は、 Adsapp.search リクエストを使用して取得できます。

更新

オペレーションで update を指定し、更新するオブジェクトをシステムが特定できるように、リソース名が指定されたオブジェクトを渡します。また、値を更新するフィールドに入力し、このリクエストで変更するフィールドを正確に示す updateMask を指定します。更新マスクにリソース名を含めないでください。

update オペレーションの例:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

結果を処理する

オペレーションタイプに関係なく、戻り値は MutateResultです。返されたリソース名を使用して、変更後のリソースの現在の状態をクエリし、オペレーションが成功したかどうか、エラーが発生した場合はどのようなエラーが発生したかを確認できます。

結果を確認してログに情報を出力する基本的なフローの例を次に示します。

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

複数のオペレーション

Google 広告スクリプトでは、1 つのリクエストで複数のオペレーションを変更することもできます。AdsApp.mutateAll1 つのリクエストで、キャンペーン階層全体など、相互に依存するエンティティを作成できます。必要に応じて、オペレーションのセット全体をアトミックにすることもできます。これにより、いずれかのオペレーションが失敗した場合、どのオペレーションも実行されなくなります。

戻り値は MutateResult オブジェクトの配列です。指定したオペレーションごとに 1 つのオブジェクトが返され、初期オペレーションと同じ順序で返されます。

この機能は Google Ads API の機能と同じように機能します。一時 ID やその他の考慮事項について詳しくは、 Google Ads API のベストプラクティスガイドをご覧ください。このガイドでは、フィールド名を表すために snake_case が使用されていますが、Google 広告スクリプトのドキュメントでは lowerCamelCase が使用されています。どちらの場合も Google 広告スクリプトで受け入れられるため、そのガイドからコードを直接コピーできます。

1 つのリクエストで複数のオペレーションを実行するには、すべてのオペレーションを配列に収集して AdsApp.mutateAll を呼び出します。mutateAll 呼び出しは、オペレーションの配列を最初の引数として受け取り、オプションの 2 番目の引数としてオプションを受け取ります。オプションには次のものがあります。

apiVersion: スクリプトのデフォルト以外のバージョンを使用する場合は、V24 などのカスタム API バージョンを指定できます。その時点で一般公開されているバージョンを使用できます。
partialFailure: このフィールドのデフォルト値は true です。true に設定すると、有効なオペレーションが実行され、失敗したオペレーションはエラーを返します。false に設定すると、オペレーションが失敗した場合、どのオペレーションも実行されず、このオペレーションのセットがアトミックになります。

複数のオペレーションを含む例を次に示します。この例では、アトミックリクエストでキャンペーンの予算、キャンペーン、広告グループを作成します。

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});

Mutate コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。