根據預設，單一 API 要求中的作業會以一組動作的形式執行，也就是說，如果任何單一作業失敗，整批作業就會一併失敗，否則就會全部成功。部分服務支援 partialFailure 屬性，可變更這項行為。如要進一步瞭解變動作業語意，請參閱「變動資源」。
建立
建立作業會產生新實體，且必須包含您要建立資源的完整 JSON 表示法。
POST/v21/customers/CUSTOMER_ID/campaigns:mutateHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-token:DEVELOPER_TOKEN{"operations":[{"create":{"name":"An example campaign","status":"PAUSED","campaignBudget":"customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID","advertisingChannelType":"SEARCH","networkSettings":{"targetGoogleSearch":true,"targetSearchNetwork":true,"targetContentNetwork":true,"targetPartnerSearchNetwork":false},"target_spend":{}}}]}
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-08-27 (世界標準時間)。"],[[["\u003cp\u003eThe \u003ccode\u003eMutate\u003c/code\u003e method allows for creating, updating, or removing Google Ads resources using a single API call by sending an array of operations in the request body.\u003c/p\u003e\n"],["\u003cp\u003eTo construct the \u003ccode\u003eMutate\u003c/code\u003e URL, omit the trailing resource ID from the resource name and append \u003ccode\u003e:mutate\u003c/code\u003e to it.\u003c/p\u003e\n"],["\u003cp\u003eCreate operations require a full JSON representation of the new resource, while update operations utilize an \u003ccode\u003eupdateMask\u003c/code\u003e to specify fields to modify.\u003c/p\u003e\n"],["\u003cp\u003eRemove operations simply need the \u003ccode\u003eresourceName\u003c/code\u003e to be deleted and will set its status to \u003ccode\u003eREMOVED\u003c/code\u003e.\u003c/p\u003e\n"]]],["The `Mutate` method, invoked via HTTP `POST`, modifies resources like campaigns. It uses a resource-specific URL ending in `:mutate` and a JSON body with an `operations` array. Each operation can `create`, `update`, or `remove` resources. `Create` adds new entities without a `resourceName`; `update` modifies existing ones using `updateMask` to specify changes. `Remove` deletes resources, requiring only the `resourceName`. A single `Mutate` call can perform thousands of operations.\n"],null,["# Mutate\n\n| **Note:** See the [Mutates](/google-ads/api/rest/examples#mutates) section of the accompanying examples for more complete examples.\n\nMost resources are modified (created, updated, or removed) using a `Mutate`\nmethod. The `Mutate` method is invoked as an HTTP `POST` to a resource-specific\nURL that matches the resource-name pattern, without the trailing resource ID.\nThe IDs of the resources to be mutated are instead sent in the JSON request\nbody. This lets you send a single API call that contains multiple operations on\ndifferent resources.\n\nFor example, a campaign's resource name uses the following format: \n\n```html\ncustomers/CUSTOMER_ID/campaigns/CAMPAIGN_ID\n```\n\nTo derive the URL used for mutating campaigns, omit the trailing resource ID and\nappend `:mutate`: \n\n```html\nhttps://googleads.googleapis.com/v21/customers/CUSTOMER_ID/campaigns:mutate\n```\n\nA `Mutate` message contains a top-level JSON object with an `operations` array\nthat can contain many `operation` objects. Each operation, in turn, can be one\nof: `create`, `update`, or `remove`. These are the only possible mutate\noperations. \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/campaigns:mutate HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n \"operations\": [\n ...\n ]\n}\n```\n\nMost services support thousands of operations in a single API call. The [System\nLimits](/google-ads/api/docs/best-practices/system-limits) guide documents the\nlimitations on request sizes.\n\nOperations within a single API request are executed as one set of actions by\ndefault, meaning they either all succeed together or the whole batch fails if\nany single operation fails. Some services support a\n[`partialFailure`](/google-ads/api/docs/best-practices/partial-failures) attribute\nto change this behavior. See [Mutating Resources](/google-ads/api/docs/mutating/overview)\nfor more detailed information on mutate operation semantics.\n\nCreate\n------\n\nCreate operations produce new entities and must include a full JSON\nrepresentation of the resource you intend to create.\n**Key Point:** Create operations don't specify a `resourceName` or ID. When the API call succeeds, the response includes the `resourceName` generated for the newly created object. \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/campaigns:mutate HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n \"operations\": [\n {\n \"create\": {\n \"name\": \"An example campaign\",\n \"status\": \"PAUSED\",\n \"campaignBudget\": \"customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/campaignBudgets/\u003cvar translate=\"no\"\u003eCAMPAIGN_BUDGET_ID\u003c/var\u003e\",\n \"advertisingChannelType\": \"SEARCH\",\n \"networkSettings\": {\n \"targetGoogleSearch\": true,\n \"targetSearchNetwork\": true,\n \"targetContentNetwork\": true,\n \"targetPartnerSearchNetwork\": false\n },\n \"target_spend\": {}\n }\n }\n ]\n}\n```\n\nUpdate\n------\n\nUpdate operations perform sparse updates to an existing resource. You only need\nto specify the fields you want to modify.\n\nTo specify the fields that you want to update, set the `updateMask` attribute to\na comma-separated list of field names. This is particularly useful if you\nalready have a fully formed JSON representation of an object (for instance, as\nreturned by a previous API call), but only want to change certain fields.\nInstead of pruning the JSON object, you can just list the field names to be\nmodified in the `updateMask` and send the entire JSON object.\n| **Key Point:** The `update_mask` is a [standard field](//cloud.google.com/apis/design/standard_fields) used across Google APIs to facilitate performing partial updates on a given resource. See [`FieldMask` reference documentation](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto) for full details.\n\nThe example below changes the `name` and `status` of an existing campaign having\nthe given `resourceName`. \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/campaigns:mutate HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n \"operations\": [\n {\n \"updateMask\": \"name,status\",\n \"update\": {\n \"resourceName\": \"customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/campaigns/\u003cvar translate=\"no\"\u003eCAMPAIGN_ID\u003c/var\u003e\",\n \"name\": \"My renamed campaign\",\n \"status\": \"PAUSED\",\n }\n }\n ]\n}\n```\n\nRemove\n------\n\nRemove operations effectively delete an object, setting its Google Ads status to\n`REMOVED`. Only the `resourceName` to be removed is required. \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/campaigns:mutate HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n \"operations\": [\n {\n \"remove\": \"customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/campaigns/\u003cvar translate=\"no\"\u003eCAMPAIGN_ID\u003c/var\u003e\"\n }\n ]\n}\n```"]]
