En esta guía, se describe la estructura común de todas las llamadas a la API.
Si usas una biblioteca cliente para interactuar con la API, no necesitarás conocer los detalles de la solicitud subyacente. Sin embargo, tener algunos conocimientos sobre la estructura de las llamadas a la API puede ser útil durante las pruebas y la depuración.
La API de Google Ads es una API de gRPC con vinculaciones de REST. Esto significa que hay dos formas de realizar llamadas a la API.
Preferido:
Crea el cuerpo de la solicitud como un búfer de protocolo.
Envía la solicitud al servidor con HTTP/2.
Deserializa la respuesta en un búfer de protocolo.
Interpreta los resultados.
La mayor parte de nuestra documentación describe el uso de gRPC.
Opcional:
Crea el cuerpo de la solicitud como un objeto JSON.
Envía la solicitud al servidor con HTTP 1.1.
Deserializa la respuesta como un objeto JSON.
Interpreta los resultados.
Consulta la guía de la interfaz de REST para obtener más información sobre el uso de REST.
Nombres de recursos
La mayoría de los objetos de la API se identifican por sus cadenas de nombres de recursos. Estas cadenas también funcionan como URLs cuando se usa la interfaz de REST. Consulta la estructura de los nombres de recursos de la interfaz de REST.
IDs compuestos
Si el ID de un objeto no es único a nivel global, se construye un ID compuesto para ese objeto anteponiendo su ID principal y una virgulilla (~).
Por ejemplo, dado que el ID de un anuncio del grupo de anuncios no es único a nivel global, le anteponemos el ID de su objeto principal (grupo de anuncios) para crear un ID compuesto único:
AdGroupId
de123
+~
+AdGroupAdId
de45678
= ID del anuncio compuesto del grupo de anuncios de123~45678
.
Encabezados de la solicitud
Estos son los encabezados HTTP (o los metadatos de grpc) que acompañan al cuerpo de la solicitud:
Autorización
Debes incluir un token de acceso de OAuth2 en el formato Authorization: Bearer YOUR_ACCESS_TOKEN
que identifique una cuenta de administrador que actúe en nombre de un cliente o un anunciante que administre directamente su propia cuenta. En la guía de OAuth2, se encuentran las instrucciones para recuperar un token de acceso. Un token de acceso es válido durante una hora después de que lo adquieres. Cuando vence, actualiza el token de acceso para recuperar uno nuevo. Ten en cuenta que nuestras bibliotecas cliente actualizan automáticamente los tokens vencidos.
developer-token
Un token de desarrollador es una cadena de 22 caracteres que identifica de forma única a un desarrollador de la API de Google Ads. Un ejemplo de cadena de token de desarrollador es ABcdeFGH93KL-NOPQ_STUv
. El token de desarrollador debe incluirse en el formato developer-token : ABcdeFGH93KL-NOPQ_STUv
.
login-customer-id
Es el ID del cliente autorizado para usar en la solicitud, sin guiones (-
). Si accedes a la cuenta de cliente a través de una cuenta de administrador, este encabezado es obligatorio y debe establecerse en el ID de cliente de la cuenta de administrador.
https://googleads.googleapis.com/v20/customers/1234567890/campaignBudgets:mutate
Establecer login-customer-id
equivale a elegir una cuenta en la IU de Google Ads después de acceder o hacer clic en tu imagen de perfil en la parte superior derecha. Si no incluyes este encabezado, se usará el cliente operativo de forma predeterminada.
linked-customer-id
Este encabezado solo lo utilizan los [proveedores de estadísticas de aplicaciones de terceros cuando suben conversiones a una cuenta de Google Ads vinculada.
Considera la situación en la que los usuarios de la cuenta A
proporcionan acceso de lectura y edición a sus entidades a la cuenta B
a través de un ThirdPartyAppAnalyticsLink
.
Una vez vinculada, un usuario de la cuenta B
puede realizar llamadas a la API en la cuenta A
, sujeto a los permisos que proporciona la vinculación. En este caso, los permisos de llamada a la API para la cuenta A
se determinan por la vinculación de terceros a la cuenta B
, en lugar de la relación de cuenta de administrador que se usa en otras llamadas a la API.
El proveedor de estadísticas de aplicaciones de terceros realiza una llamada a la API de la siguiente manera:
linked-customer-id
: Es la cuenta de estadísticas de aplicaciones de terceros que sube los datos (cuentaB
).customer-id
: Cuenta de Google Ads a la que se suben los datos (cuentaA
).- Encabezados
login-customer-id
yAuthorization
: Combinación de valores para identificar a un usuario que tiene acceso a la cuentaB
.
Encabezados de respuesta
Los siguientes encabezados (o metadatos finales de gRPC) se devuelven con el cuerpo de la respuesta. Te recomendamos que registres estos valores para depurar.
request-id
El request-id
es una cadena que identifica de forma única esta solicitud.