建立、更新或移除資源。這個方法支援包含多個資源類型的不可部分交易交易。舉例來說,您可以選擇自動建立廣告活動和廣告活動預算,或是自動執行多達數千次變更。
此方法基本上就是環繞一系列 change 方法的包裝函式。比起直接呼叫這些方法,我們只提供下列功能:
- 不可部分完成的交易
- 臨時資源名稱 (如下所述)
- 可縮短一連串變更呼叫的延遲時間
注意:系統只會納入支援不可部分完成交易的資源,因此無法取代對個別服務的所有呼叫。
原子交易優勢
原子性可簡化錯誤處理流程。如果您進行多項變更而失敗,可能會導致帳戶出現不一致的狀態。採用不可分割後,您可以直接達到所選狀態,否則要求失敗,您可以重試。
臨時資源名稱
臨時資源名稱是一種特殊的資源名稱類型,可用來建立資源,並在相同的要求中參照該資源。舉例來說,如果建立廣告活動預算的 resourceName
等於 customers/123/campaignBudgets/-1
,該資源名稱就可以在同一個要求的 Campaign.budget
欄位中重複使用。這樣一來,系統就會以不可分割的形式建立這兩項資源並建立連結。
如要建立臨時資源名稱,請在伺服器通常會分配的名稱中加入負數。
注意:
- 必須以臨時名稱建立資源,才能重複使用該名稱。舉例來說,如果將變動順序撤銷,先前的 CampaignBudget+Campaign 範例就會失敗。
- 每次要求時,系統不會記住臨時名稱。
- 要求中的臨時名稱數量沒有限制。
- 每個臨時名稱都必須使用不重複的負數,即使資源類型不同也一樣。
延遲時間
請務必按照資源類型將變更分組,否則要求可能會逾時並失敗。延遲時間大致等於一連串對個別變更方法的呼叫,其中每個資源類型變更都是新的呼叫。舉例來說,先將 10 個廣告活動設為 10 個廣告群組,就像 2 個來電一樣,而更改 1 個廣告活動、1 個廣告群組、1 個廣告活動、1 個廣告群組,呼叫上限為 4 次。
CampaignBudgetErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError
HTTP 要求
POST https://googleads.googleapis.com/v14/customers/{customerId}/googleAds:mutate
這個網址使用 gRPC 轉碼語法。
路徑參數
參數 | |
---|---|
customerId |
必要欄位。要修改資源的客戶 ID。 |
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "mutateOperations": [ { object ( |
欄位 | |
---|---|
mutateOperations[] |
必要欄位。要對個別資源執行的作業清單。 |
partialFailure |
如果為 true,系統就會執行成功的作業,且無效的作業會傳回錯誤。如果為 false,只有在所有作業皆有效的情況下,系統才會在單筆交易中執行所有作業。預設值為 false。 |
validateOnly |
如果為 true,則驗證要求但尚未執行。系統只會傳回錯誤,而非傳回結果。 |
responseContentType |
回應內容類型設定。決定在異動後應傳回可變動資源,還是只傳回資源名稱。只有在資源包含適當的回應欄位時,系統才會傳回可變動資源。例如 MutateCampaignResult.campaign。 |
回應主體
GoogleAdsService.Mutate
的回應訊息。
如果成功,回應主體即會包含具有以下結構的資料:
JSON 表示法 |
---|
{ "partialFailureError": { object ( |
欄位 | |
---|---|
partialFailureError |
在部分失敗模式下,與作業失敗相關的錯誤。只有在部分失敗 = true 且作業內發生所有錯誤時,才會傳回這個編號。如果在作業之外發生任何錯誤 (例如驗證錯誤),我們會傳回遠端程序呼叫 (RPC) 層級錯誤。 |
mutateOperationResponses[] |
變更的所有回應。 |
授權範圍
需要下列 OAuth 範圍:
https://www.googleapis.com/auth/adwords
詳情請參閱 OAuth 2.0 總覽。