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 automática, o bien realizar hasta miles de modificaciones automáticamente.

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

  • Transacciones atómicas
  • Nombres de recursos temporales (descritos a continuación)
  • Menor latencia en comparación con hacer 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 Atomic Transaction

La atomicidad facilita mucho el manejo de errores. Si realizas una serie de cambios y uno falla, es posible que el estado de tu cuenta sea incoherente. Con la atomicidad, puedes alcanzar el 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 el presupuesto de una campaña con un resourceName igual a customers/123/campaignBudgets/-1, se puede volver a usar ese nombre de recurso en el campo Campaign.budget de la misma solicitud. De esa 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 asignaría normalmente.

Nota:

  • Los recursos se deben crear con un nombre temporal antes de que se pueda volver a usar. Por ejemplo, el ejemplo anterior de CampaignBudget + Campaign fallará si se revirtiera el orden de modificació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, la solicitud podría agotar el tiempo de espera y fallar. La latencia es aproximadamente igual a una serie de llamadas a métodos individuales de mutación, en la que cada cambio en el tipo de recurso es una llamada nueva. Por ejemplo, si mutas 10 campañas, entonces 10 grupos de anuncios es como 2 llamadas, mientras que cambiar 1 campaña, 1 grupo de anuncios, 1 campaña y 1 grupo de anuncios equivale a 4 llamadas.

AdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

Solicitud HTTP

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

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

Parámetros de ruta de acceso

Parámetros
customerId

string

Obligatorio. El ID del cliente cuyos recursos se modifican.

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)

Obligatorio. La lista de operaciones que se deben realizar en recursos individuales.
partialFailure

boolean

Si es verdadero, se llevarán a cabo operaciones exitosas y las operaciones no válidas mostrarán errores. Si es falso, todas las operaciones se llevarán a cabo en una 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 muestran errores, no resultados.
responseContentType

enum (ResponseContentType)

La configuración del tipo de contenido de la respuesta. Determina si el recurso mutable o solo el nombre del recurso se debe mostrar después de la mutación. El recurso mutable solo se mostrará si el recurso 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 operativas en el modo de falla parcial. Solo se muestra cuando partialFailure = true y todos los errores ocurren dentro de las operaciones. Si se produce algún error fuera de las operaciones (por ejemplo, errores de autenticación), se muestra un error de nivel de RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Todas las respuestas para la función {i>mutate<i}.

Permisos de autorización

Requiere el siguiente alcance de OAuth:

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

Para obtener más información, consulta la Descripción general de OAuth 2.0.