돌연변이

참고: 더 완전한 예는 함께 제공되는 예시의 변경 섹션을 참고하세요.

대부분의 리소스는 Mutate 메서드를 사용하여 수정 (생성, 업데이트 또는 삭제)됩니다. Mutate 메서드는 후행 리소스 ID 없이 리소스 이름 패턴과 일치하는 리소스별 URL에 대한 HTTP POST로 호출됩니다. 대신 변형할 리소스의 ID가 JSON 요청 본문으로 전송됩니다. 이렇게 하면 여러 리소스에 대한 여러 작업이 포함된 단일 API 호출을 전송할 수 있습니다.

예를 들어 캠페인의 리소스 이름은 다음 형식을 사용합니다.

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

캠페인 변형에 사용되는 URL을 파생하려면 뒤의 리소스 ID를 생략하고 :mutate를 추가합니다.

https://googleads.googleapis.com/v19/customers/CUSTOMER_ID/campaigns:mutate

Mutate 메시지에는 여러 operation 객체를 포함할 수 있는 operations 배열이 있는 최상위 JSON 객체가 포함됩니다. 각 작업은 create, update, remove 중 하나일 수 있습니다. 다음은 가능한 유일한 변형 작업입니다.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    ...
  ]
}

대부분의 서비스는 단일 API 호출에서 수천 개의 작업을 지원합니다. 시스템 한도 가이드에서는 요청 크기에 관한 제한사항을 설명합니다.

단일 API 요청 내의 작업은 기본적으로 하나의 작업 집합으로 실행됩니다. 즉, 작업이 하나라도 실패하면 모두 함께 성공하거나 전체 일괄 처리가 실패합니다. 일부 서비스는 이 동작을 변경하는 partialFailure 속성을 지원합니다. 변형 작업 시맨틱에 관한 자세한 내용은 리소스 변형을 참고하세요.

만들기

만들기 작업은 새 항목을 생성하며 만들려는 리소스의 전체 JSON 표현을 포함해야 합니다.

핵심사항: 만들기 작업은 resourceName 또는 ID를 지정하지 않습니다. API 호출에 성공하면 응답에 새로 생성된 객체에 대해 생성된 resourceName가 포함됩니다.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-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 객체를 전송하면 됩니다.

핵심 사항: update_mask는 지정된 리소스에 대한 부분 업데이트를 쉽게 수행하기 위해 Google API 전반에서 사용되는 표준 필드입니다. 자세한 내용은 FieldMask 참조 문서를 참고하세요.

아래 예에서는 지정된 resourceName가 있는 기존 캠페인의 name 및 status를 변경합니다.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

삭제

삭제 작업은 객체를 효과적으로 삭제하여 Google Ads 상태를 REMOVED로 설정합니다. 삭제할 resourceName만 필요합니다.

POST /v19/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "operations": [
    {
      "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID"
    }
  ]
}