Method: customers.googleAds.mutate

建立、更新或移除資源。此方法支援包含多種資源類型的不可分割交易，舉例來說，您可以一次建立廣告活動和廣告活動預算，也可以一次執行多達數千個變更。

本質上是一組 mut 方法的包裝函式。相較於直接呼叫這些方法，這項工具只提供下列功能：

  • 不可分割的交易
  • 臨時資源名稱 (如下所述)
  • 相較於發出一連串變更呼叫，系統會稍微縮短延遲時間

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

原子交易優點

不可分割性能簡化錯誤處理。如果您同時進行一連串的變更，但其中一個失敗，可能會導致帳戶狀態不一致。如果具備不可分割性，您可以直接達到所選狀態，或者要求失敗，也可以重試。

臨時資源名稱

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

如要建立臨時資源名稱，請在伺服器通常會分配的名稱部分加上負數。

注意事項：

  • 必須以臨時名稱建立資源，才能重複使用該名稱。舉例來說，如果反轉變更順序，先前的 CampaignBudget+Campaign 範例就會失敗。
  • 系統不會記住所有要求的臨時名稱。
  • 請求中的臨時名稱數量沒有限制。
  • 即使資源類型不同，每個臨時名稱都必須使用專屬的負數。

延遲時間

請務必按資源類型將變更分組，否則請求可能會逾時並失敗。延遲時間大約等於一系列對個別 mut 方法的呼叫，在資源類型中每次變更都是一個新的呼叫。舉例來說，排除 10 個廣告活動後，10 個廣告群組就像 2 次來電，而其他 1 個廣告活動、1 個廣告群組、1 個廣告活動和 1 個廣告群組就像 4 通來電。

List of errorn errors{AdCustomizerError} AdErrorAdGroupAdErrorAdGroupCriterionErrorBiddingErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

HTTP 要求

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

部分失敗模式下的作業失敗相關錯誤。只有在部分失敗 = true 且所有錯誤發生於作業內部時，才會傳回這個值。如果在作業之外發生任何錯誤 (例如驗證錯誤)，系統會傳回遠端程序呼叫 (RPC) 層級錯誤。
mutateOperationResponses[]

object (MutateOperationResponse)

針對 修改 的所有回應。

授權範圍

需要下列 OAuth 範圍：

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

詳情請參閱 OAuth 2.0 總覽。