대부분의 리소스는 Mutate 메서드를 사용하여 수정됩니다 (생성, 업데이트 또는 삭제). Mutate 메서드는 리소스 이름 패턴과 일치하는 리소스별 URL에 대한 HTTP POST로 호출되며, 후행 리소스 ID는 없습니다.
대신 변경할 리소스의 ID가 JSON 요청 본문으로 전송됩니다. 이를 통해 서로 다른 리소스에 대한 여러 작업이 포함된 단일 API 호출을 전송할 수 있습니다.
대부분의 서비스는 단일 API 호출에서 수천 개의 작업을 지원합니다. 시스템 한도 가이드에는 요청 크기에 관한 제한사항이 문서화되어 있습니다.
단일 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":{}}}]}
업데이트
업데이트 작업은 기존 리소스에 대한 스파스 업데이트를 실행합니다. 수정할 필드만 지정하면 됩니다.
업데이트할 필드를 지정하려면 updateMask 속성을 쉼표로 구분된 필드 이름 목록으로 설정합니다. 이는 객체의 JSON 표현이 이미 완전히 형성되어 있지만 (예: 이전 API 호출에서 반환됨) 특정 필드만 변경하려는 경우에 특히 유용합니다.
JSON 객체를 정리하는 대신 updateMask에서 수정할 필드 이름을 나열하고 전체 JSON 객체를 전송하면 됩니다.
아래 예에서는 지정된 resourceName이 있는 기존 캠페인의 name 및 status을 변경합니다.
[[["이해하기 쉬움","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-09-05(UTC)"],[[["\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```"]]
