Method: customers.googleAds.mutate

建立、更新或移除資源。這個方法支援使用多種資源類型的原子交易。舉例來說，您可以使用原子操作建立廣告活動和廣告活動預算，或以原子操作執行多達數千次的變異操作。

這個方法基本上是一系列變異方法的包裝函式。相較於直接呼叫這些方法，它提供的唯一功能如下：

  • 不可分割的交易
  • 臨時資源名稱 (如下所述)
  • 比起發出一系列變異呼叫，延遲時間略有縮短

注意：系統只會納入支援不可中斷交易的資源，因此這個方法無法取代對個別服務的所有呼叫。

不可分割交易的好處

原子性可讓錯誤處理作業更加輕鬆。如果您要進行一系列變更，其中一個變更失敗，帳戶可能會處於不一致的狀態。有了原子性，您可以直接達到所選狀態，或者要求失敗，您可以重試。

臨時資源名稱

臨時資源名稱是一種特殊類型的資源名稱，用於在同一個要求中建立資源並參照該資源。舉例來說，如果建立廣告活動預算時，resourceName 等於 customers/123/campaignBudgets/-1，則該資源名稱可在同一個要求的 Campaign.budget 欄位中重複使用。這樣一來，這兩個資源就會以原子方式建立及連結。

如要建立臨時資源名稱，請在伺服器通常會指派的名稱部分中，放入負數。

注意：

  • 資源必須使用暫時名稱建立，才能重複使用。舉例來說，如果變更順序反轉，先前的 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

這個網址使用 gRPC 轉碼語法。

路徑參數

參數
customerId

string

必要欄位。資源所屬客戶的 ID。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
欄位
mutateOperations[]

object (MutateOperation)

必要欄位。要在個別資源上執行的作業清單。
partialFailure

boolean

如果為 true，系統會執行成功的作業，並傳回無效作業的錯誤。如果設為 false，只有在所有作業都有效時，系統才會在單一交易中執行所有作業。預設值為 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)

所有 mutate 回應。

授權範圍

需要下列 OAuth 範圍：

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

詳情請參閱 OAuth 2.0 Overview。