Method: customers.googleAds.mutate

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

このメソッドは、基本的に一連の mutate メソッドをラップするものです。これらのメソッドを直接呼び出す場合と比べて、このクラスが提供する機能は次のとおりです。

  • アトミック トランザクション
  • 一時リソース名（後述）
  • 一連のミューテーション コールよりもレイテンシが若干短縮

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

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

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

一時リソース名

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

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

注:

  • 名前を再利用するには、リソースを一時的な名前で作成する必要があります。たとえば、前の CampaignBudget+Campaign の例では、ミューテーションの順序が逆になると失敗します。
  • 一時的な名前は、複数のリクエスト間では記憶されません。
  • リクエスト内の一時的な名前の数に制限はありません。
  • リソースタイプが異なる場合でも、一時的な名前はそれぞれ、一意の負の数を使用する必要があります。

レイテンシ

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

スローされるエラーのリスト: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

HTTP リクエスト

POST https://googleads.googleapis.com/v19/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 Overview をご覧ください。