Method: customers.googleAds.mutate

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

このメソッドは基本的に、一連の mut メソッドのラッパーです。これらのメソッドを直接呼び出す場合と比べて、次の機能しか提供されません。

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

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

アトミックな取引特典

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

一時リソース名

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

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

注:

  • リソース名を再利用するには、その前に一時名でリソースを作成する必要があります。たとえば、前の CampaignBudget+Campaign の例では、変更の順序が逆になると失敗します。
  • 一時名は、リクエスト間で保持されません。
  • リクエストに含める一時名の数に制限はありません。
  • リソースタイプが異なる場合でも、各一時名には一意の負の数値を使用する必要があります。

レイテンシ

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

次のエラーのリスト: AdCustomizerErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

HTTP リクエスト

POST https://googleads.googleapis.com/v16/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)

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

承認スコープ

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

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

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