Method: customers.googleAds.mutate

Crea, actualiza o quita recursos. Este método admite transacciones atómicas con varios tipos de recursos. Por ejemplo, puedes crear una campaña y un presupuesto de campaña de forma atómica, o bien realizar hasta miles de mutaciones de forma atómica.

Este método es, en esencia, un wrapper alrededor de una serie de métodos de mutación. Las únicas funciones que ofrece en comparación con llamar a esos métodos directamente son las siguientes:

  • Transacciones atómicas
  • Nombres de recursos temporales (se describen a continuación)
  • Latencia algo reducida al realizar una serie de llamadas de mutación

Nota: Solo se incluyen los recursos que admiten transacciones atómicas, por lo que este método no puede reemplazar todas las llamadas a servicios individuales.

Beneficios de las transacciones atómicas

La atomicidad facilita mucho el manejo de errores. Si realizas una serie de cambios y uno falla, tu cuenta puede quedar en un estado incoherente. Con la atomicidad, llegas al estado elegido directamente o la solicitud falla y puedes volver a intentarlo.

Nombres de recursos temporales

Los nombres de recursos temporales son un tipo especial de nombre de recurso que se usa para crear un recurso y hacer referencia a él en la misma solicitud. Por ejemplo, si se crea un presupuesto de campaña con resourceName igual a customers/123/campaignBudgets/-1, ese nombre de recurso se puede volver a usar en el campo Campaign.budget en la misma solicitud. De esta manera, los dos recursos se crean y vinculan de forma atómica.

Para crear un nombre de recurso temporal, coloca un número negativo en la parte del nombre que el servidor normalmente asignaría.

Nota:

  • Los recursos deben crearse con un nombre temporal para que se pueda volver a usar. Por ejemplo, el ejemplo anterior de CampaignBudget+Campaign fallaría si se invirtiera el orden de mutación.
  • Los nombres temporales no se recuerdan en las solicitudes.
  • No hay límite para la cantidad de nombres temporales en una solicitud.
  • Cada nombre temporal debe usar un número negativo único, incluso si los tipos de recursos difieren.

Latencia

Es importante agrupar las mutaciones por tipo de recurso, de lo contrario, es posible que se agote el tiempo de espera de la solicitud y falle. La latencia es aproximadamente igual a una serie de llamadas a métodos de mutación individuales, en los que cada cambio en el tipo de recurso es una llamada nueva. Por ejemplo, mutar 10 campañas y, luego, 10 grupos de anuncios es como realizar 2 llamadas, mientras que mutar 1 campaña, 1 grupo de anuncios, 1 campaña y 1 grupo de anuncios es como realizar 4 llamadas.

Lista de errores generados: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

Solicitud HTTP

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de ruta de acceso

Parámetros
customerId

string

Es obligatorio. El ID del cliente cuyos recursos se están modificando.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Representación JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Campos
mutateOperations[]

object (MutateOperation)

Es obligatorio. Es la lista de operaciones que se deben realizar en recursos individuales.
partialFailure

boolean

Si es verdadero, se llevarán a cabo las operaciones correctas y las operaciones no válidas mostrarán errores. Si es falso, todas las operaciones se llevarán a cabo en una sola transacción solo si todas son válidas. El valor predeterminado es falso.
validateOnly

boolean

Si es verdadero, la solicitud se valida, pero no se ejecuta. Solo se devuelven errores, no resultados.
responseContentType

enum (ResponseContentType)

Es la configuración del tipo de contenido de la respuesta. Determina si se debe mostrar el recurso mutable o solo el nombre del recurso después de la mutación. El recurso mutable solo se mostrará si tiene el campo de respuesta adecuado. Por ejemplo, MutateCampaignResult.campaign.

Cuerpo de la respuesta

Mensaje de respuesta para GoogleAdsService.Mutate.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Representación JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Campos
partialFailureError

object (Status)

Errores relacionados con fallas de operación en el modo de falla parcial. Solo se muestra cuando partialFailure = true y todos los errores se producen dentro de las operaciones. Si se produce algún error fuera de las operaciones (por ejemplo, errores de autenticación), devolvemos un error a nivel de la RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Todas las respuestas para la mutación.

Permisos de autorización

Requiere el siguiente alcance de OAuth:

  • https://www.googleapis.com/auth/adwords

Para obtener más información, consulta OAuth 2.0 Overview.