Modificar

Nota: Consulta la sección Mutates de los ejemplos adjuntos para ver ejemplos más completos.

La mayoría de los recursos se modifican (se crean, se actualizan o se quitan) con un método Mutate. El método Mutate se invoca como un POST HTTP a una URL específica del recurso que coincide con el patrón de nombre de recurso, sin el ID de recurso final. En su lugar, los IDs de los recursos que se van a mutar se envían en el cuerpo de la solicitud JSON. Esto te permite enviar una sola llamada a la API que contiene varias operaciones en diversos recursos.

Por ejemplo, el nombre del recurso de una campaña usa el siguiente formato:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

Para derivar la URL que se usa para mutar campañas, omite el ID de recurso final y agrega :mutate:

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

Un mensaje Mutate contiene un objeto JSON de nivel superior con un array operations que puede contener muchos objetos operation. Cada operación, a su vez, puede ser una de las siguientes: create, update o remove. Estas son las únicas operaciones de mutación posibles.

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": [
    ...
  ]
}

La mayoría de los servicios admiten miles de operaciones en una sola llamada a la API. En la guía Límites del sistema, se documentan las limitaciones en los tamaños de las solicitudes.

De forma predeterminada, las operaciones dentro de una sola solicitud a la API se ejecutan como un conjunto de acciones, lo que significa que todas se completan juntas o falla todo el lote si falla una sola operación. Algunos servicios admiten un atributo partialFailure para cambiar este comportamiento. Consulta Cómo modificar recursos para obtener información más detallada sobre la semántica de la operación de mutación.

Crear

Las operaciones de creación producen entidades nuevas y deben incluir una representación JSON completa del recurso que deseas crear.

Punto clave: Las operaciones de creación no especifican un resourceName ni un ID. Cuando la llamada a la API se realiza correctamente, la respuesta incluye el resourceName generado para el objeto creado recientemente.

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": {}
      }
    }
  ]
}

Actualizar

Las operaciones de actualización realizan actualizaciones dispersas en un recurso existente. Solo necesitas especificar los campos que deseas modificar.

Para especificar los campos que deseas actualizar, establece el atributo updateMask en una lista de nombres de campo separados por comas. Esto es particularmente útil si ya tienes una representación JSON completamente formada de un objeto (por ejemplo, como muestra una llamada a la API anterior), pero solo quieres cambiar ciertos campos. En lugar de podar el objeto JSON, puedes enumerar los nombres de los campos que se modificarán en updateMask y enviar todo el objeto JSON.

Punto clave: update_mask es un campo estándar que se usa en todas las APIs de Google para facilitar la realización de actualizaciones parciales en un recurso determinado. Consulta la documentación de referencia de FieldMask para obtener todos los detalles.

En el siguiente ejemplo, se cambian los name y status de una campaña existente que tiene el resourceName determinado.

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",
      }
    }
  ]
}

Quitar

Las operaciones de eliminación borran de forma efectiva un objeto y establecen su estado de Google Ads en REMOVED. Solo se requiere el resourceName que se quitará.

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"
    }
  ]
}