Method: customers.googleAds.mutate

リソースを作成、更新、削除します。このメソッドは、複数のタイプのリソースを使用するアトミック トランザクションをサポートしています。たとえば、キャンペーンとキャンペーンの予算をアトミックに作成したり、最大数千のミューテーションをアトミックに実行したりできます。

このメソッドは基本的に、一連の変更メソッドのラッパーです。これらのメソッドの直接呼び出しよりも、次の機能のみが提供されます。

  • アトミック トランザクション
  • 一時リソース名（後述）
  • 一連の変更呼び出しよりもレイテンシが若干短縮されます。

注: アトミック トランザクションをサポートするリソースのみが含まれるため、このメソッドで個々のサービスへのすべての呼び出しを置き換えることはできません。

アトミック トランザクションのメリット

アトミック性により、エラー処理がはるかに容易になります。何度か変更を加えても、1 つでもうまくいかない場合、アカウントに対して一貫性のない状態になる可能性があります。アトミック性を使用すると、選択した状態に直接到達するか、リクエストが失敗して再試行できます。

一時リソース名

一時リソース名は、リソースを作成し、同じリクエストでそのリソースを参照するために使用される特別なタイプのリソース名です。たとえば、キャンペーン予算が customers/123/campaignBudgets/-1 と等しい resourceName で作成された場合、そのリソース名は、同じリクエストの Campaign.budget フィールドで再利用できます。このようにして、2 つのリソースがアトミックに作成され、リンクされます。

一時リソース名を作成するには、通常サーバーが割り当てる名前の部分に負の数を挿入します。

注:

  • リソース名を再利用するには、まず一時名を指定してリソースを作成する必要があります。たとえば前の「キャンペーン予算とキャンペーン」の例では、変更の順序が逆になっていると失敗します。
  • 一時名はリクエスト間で記憶されません。
  • リクエスト内の温度名の数に制限はありません。
  • リソースタイプが異なる場合でも、各一時名には一意の負の数を使用する必要があります。

レイテンシ

リソースタイプで変更をグループ化することが重要です。そうしないと、リクエストがタイムアウトして失敗する可能性があります。レイテンシは、個々の ミューテーション メソッドを連続して呼び出すのとほぼ等しくなります。リソースタイプが変わるたびに新しい呼び出しとなります。たとえば、キャンペーンを 10 個変更し、広告グループを 10 個変更すると 2 回の呼び出しに相当するようになります。一方、キャンペーン 1 個、広告グループ 1 個、キャンペーン 1 個、広告グループ 1 個を変更する場合は、呼び出し 4 回としてカウントされます。

次のエラーのリストをご覧ください。AdCustomizerErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

HTTP リクエスト

POST https://googleads.googleapis.com/v15/customers/{customerId}/googleAds:mutate

この URL は gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
customerId

string

必須。リソースが変更される顧客の ID。

リクエスト本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
フィールド
mutateOperations[]

object (MutateOperation)

必須。個々のリソースに対して実行するオペレーションのリスト。
partialFailure

boolean

true の場合、成功したオペレーションが実行され、無効なオペレーションはエラーを返します。false の場合、すべての操作が有効である場合にのみ、すべての操作が 1 つのトランザクションで実行されます。デフォルトは false です。
validateOnly

boolean

true の場合、リクエストは検証されますが、実行されません。エラーのみが返され、結果は返されません。
responseContentType

enum (ResponseContentType)

レスポンスのコンテンツ タイプの設定。ミューテーション後に可変リソースを返すか、リソース名のみを返すかを決定します。可変リソースは、リソースに適切なレスポンス フィールドがある場合にのみ返されます。（例: MutateCampaignResult.campaign）。

レスポンスの本文

GoogleAdsService.Mutate に対するレスポンス メッセージです。

成功すると、レスポンスの本文に次の構造のデータが含まれます。

JSON 表現 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
フィールド
partialFailureError

object (Status)

部分障害モードのオペレーションの失敗に関連するエラー。partialFailure が true で、オペレーション内ですべてのエラーが発生した場合にのみ返されます。オペレーションの外部でエラー（認証エラーなど）が発生した場合は、RPC レベルのエラーが返されます。
mutateOperationResponses[]

object (MutateOperationResponse)

mut に対するすべてのレスポンス。

認可スコープ

次の OAuth スコープが必要です。

  • https://www.googleapis.com/auth/adwords

詳細については、OAuth 2.0 の概要をご覧ください。