API de terceros

Una función potente de los scripts de Google Ads es la capacidad de integrarse con datos y servicios de APIs de terceros.

En esta guía, se abordan los siguientes conceptos que pueden ayudarte a escribir secuencias de comandos para conectarte a otros servicios:

  • Realiza solicitudes HTTP: Cómo usar UrlFetchApp para acceder a APIs externas.
  • Autenticación: Se abarcan algunas situaciones de autenticación comunes.
  • Análisis de respuestas: Cómo procesar los datos JSON y XML devueltos.

También incluimos ejemplos para varias APIs populares que ilustran estos conceptos.

Recupera datos con UrlFetchApp

UrlFetchApp proporciona la funcionalidad principal necesaria para interactuar con APIs de terceros.

En el siguiente ejemplo, se muestra cómo recuperar datos meteorológicos de OpenWeatherMap. Elegimos OpenWeatherMap debido a su esquema de autorización y API relativamente sencillos.

Haz una solicitud

La documentación de OpenWeatherMap especifica el formato para solicitar el clima actual de la siguiente manera:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

La URL proporciona nuestro primer ejemplo de autorización: El parámetro apikey es obligatorio y el valor es único para cada usuario. Esta clave se obtiene a través del registro.

Después de registrarte, puedes emitir una solicitud con la clave de la siguiente manera:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

La ejecución de este código genera una cadena larga de texto JSON que se escribe en la ventana de registro de los scripts de Google Ads.

El siguiente paso es convertirlo en un formato que se pueda usar en tu secuencia de comandos.

Datos JSON

Muchas APIs proporcionan respuestas en formato JSON. Esto representa una serialización de objetos de JavaScript, de modo que los objetos, los arrays y los tipos básicos se puedan representar y transferir como cadenas.

Para volver a convertir una cadena JSON, como la que devuelve OpenWeatherMap, en un objeto de JavaScript, usa el método JSON.parse integrado. Continuando con el ejemplo anterior:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

El método JSON.parse convierte la cadena en un objeto, que tiene una propiedad name.

Consulta la sección Analiza las respuestas para obtener más detalles sobre cómo trabajar con las respuestas de la API en diferentes formatos.

Manejo de errores

El manejo de errores es un aspecto importante que se debe tener en cuenta cuando se trabaja con APIs de terceros en tus secuencias de comandos, ya que estas APIs suelen cambiar con frecuencia y generar valores de respuesta inesperados, por ejemplo:

  • La URL o los parámetros de la API pueden cambiar sin que lo sepas.
  • Tu clave de API (o cualquier otra credencial de usuario) puede vencer.
  • El formato de la respuesta puede cambiar sin previo aviso.

Códigos de estado HTTP

Debido a la posibilidad de que se produzcan respuestas inesperadas, debes inspeccionar el código de estado HTTP. De forma predeterminada, UrlFetchApp arrojará una excepción si se encuentra un código de error de HTTP. Para cambiar este comportamiento, es necesario pasar un parámetro opcional, como en el siguiente ejemplo:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

Estructura de la respuesta

Cuando las APIs de terceros cambian, es posible que no te enteres de inmediato de los cambios que podrían afectar tus secuencias de comandos. Por ejemplo, si la propiedad name que se muestra en el ejemplo de OpenWeatherMap se cambia a locationName, las secuencias de comandos que usan esta propiedad fallarán.

Por este motivo, puede ser beneficioso probar si la estructura que se muestra es la esperada, por ejemplo:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

Envía datos con POST a través de UrlFetchApp

El ejemplo introductorio con OpenWeatherMap solo recuperó datos. Por lo general, las llamadas a la API que no cambian el estado en el servidor remoto usan el método HTTP GET.

El método GET es el predeterminado para UrlFetchApp. Sin embargo, algunas llamadas a la API, como las llamadas a un servicio que envía mensajes SMS, requerirán otros métodos, como POST o PUT.

Para ilustrar el uso de llamadas POST con UrlFetchApp, en el siguiente ejemplo, se muestra la integración con Slack, una aplicación de mensajería colaborativa, para enviar un mensaje de Slack a usuarios y grupos de Slack.

Configura Slack

En esta guía, se da por sentado que ya te registraste para obtener una cuenta de Slack.

Al igual que con OpenWeatherMap en el ejemplo anterior, es necesario obtener un token para habilitar el envío de mensajes. Slack proporciona una URL única para que puedas enviar mensajes a tu equipo, llamada Webhook entrante.

Configura un webhook entrante. Para ello, haz clic en Agregar integración de webhooks entrantes y sigue las instrucciones. El proceso debe emitir una URL para usar en los mensajes.

Realiza una solicitud POST

Después de configurar el webhook entrante, para realizar una solicitud POST, se deben usar algunas propiedades adicionales en el parámetro options que se pasa a UrlFetchApp.fetch:

  • method: Como se mencionó, el valor predeterminado es GET, pero aquí lo anulamos y lo configuramos como POST.
  • payload: Son los datos que se enviarán al servidor como parte de la solicitudPOST . En este ejemplo, Slack espera un objeto serializado en formato JSON, como se describe en la documentación de Slack. Para ello, se usa el método [JSON.stringify][json-stringify-url] y Content-Type se establece en application/json.

      // Change the URL for the one issued to you from 'Setting up Slack'.
      const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
      const slackMessage = {
        text: 'Hello, slack!'
      };
    
      const options = {
        method: 'POST',
        contentType: 'application/json',
        payload: JSON.stringify(slackMessage)
      };
      UrlFetchApp.fetch(SLACK_URL, options);
    

Ejemplo extendido de Slack

En el ejemplo anterior, se muestra el código mínimo necesario para habilitar los mensajes entrantes en Slack. Una muestra extendida ilustra la creación y el envío de un informe de rendimiento de la campaña a un grupo, así como algunas opciones de formato y visualización.

Mensaje entrante

Consulta el formato de mensajes en la documentación de Slack para obtener más detalles sobre los mensajes de Slack.

Datos de formulario

En el ejemplo anterior, se mostró cómo usar una cadena JSON como la propiedad payload para la solicitud POST.

Según el formato de payload, UrlFetchApp adopta diferentes enfoques para construir la solicitud POST:

  • Cuando payload es una cadena, el argumento de cadena se envía como el cuerpo de la solicitud.
  • Cuando payload es un objeto, por ejemplo, un mapa de valores:

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
    

    Los pares clave-valor se convierten en datos de formulario:

    subject=Test&to=mail@example.com&body=Hello,+World!
    

    Además, el encabezado Content-Type de la solicitud se establece en application/x-www-form-urlencoded.

Algunas APIs requieren el uso de datos de formulario cuando se envían solicitudes POST, por lo que es útil tener en cuenta esta conversión automática de objetos de JavaScript en datos de formulario.

Autenticación básica HTTP

La autenticación básica de HTTP es una de las formas más sencillas de autenticación y la usan muchas APIs.

La autenticación se logra adjuntando un nombre de usuario y una contraseña codificados a los encabezados HTTP en cada solicitud.

Autenticación básica HTTP

Crea una solicitud

Se requieren los siguientes pasos para producir una solicitud autenticada:

  1. Para formar la frase de contraseña, une el nombre de usuario y la contraseña con dos puntos, por ejemplo, username:password.
  2. Codifica la frase de contraseña en Base64, por ejemplo, username:password se convierte en dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Adjunta un encabezado Authorization a la solicitud, con el formato Authorization: Basic <encoded passphrase>.

En el siguiente fragmento, se muestra cómo lograrlo en los scripts de Google Ads:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

Muestras de autenticación básica

La sección Muestras de código contiene dos muestras que ilustran el uso de la autenticación básica de HTTP:

Plivo

Plivo es un servicio que facilita el envío y la recepción de mensajes SMS con su API. En este ejemplo, se muestra cómo enviar mensajes.

  1. Regístrate en Plivo.
  2. Pega la secuencia de comandos de ejemplo en una secuencia de comandos nueva en Google Ads.
  3. Reemplaza los valores PLIVO_ACCOUNT_AUTHID y PLIVO_ACCOUNT_AUTHTOKEN por los valores del panel de administración.
  4. Inserta tu dirección de correo electrónico como se especifica en la secuencia de comandos para recibir notificaciones de errores.
  5. Para usar Plivo, debes comprar números o agregarlos a la cuenta de prueba. Agrega números de zona de pruebas que se puedan usar con la cuenta de prueba.
  6. Agrega el número que aparecerá como remitente y el número del destinatario.
  7. Actualiza PLIVO_SRC_PHONE_NUMBER en la secuencia de comandos a uno de los números de la zona de pruebas que acabas de registrar. Debe incluir el código de país internacional, por ejemplo, 447777123456 para un número del Reino Unido.

Twilio

Twilio es otro servicio que facilita el envío y la recepción de mensajes SMS con su API. En este ejemplo, se muestra cómo enviar mensajes.

  1. Regístrate en Twillio.
  2. Pega la secuencia de comandos de ejemplo en una secuencia de comandos nueva en Google Ads.
  3. Reemplaza los valores TWILIO_ACCOUNT_SID y TWILIO_ACCOUNT_AUTHTOKEN por los valores que se muestran en la página de la consola de la cuenta.
  4. Reemplaza TWILIO_SRC_PHONE_NUMBER por el número del panel, que es el número autorizado por Twilio para enviar mensajes.

OAuth 1.0

Muchos servicios populares usan OAuth para la autenticación. OAuth viene en varios tipos y versiones.

Mientras que con la autenticación básica de HTTP, un usuario tiene solo un nombre de usuario y una contraseña, OAuth permite que se otorgue acceso a la cuenta y los datos de un usuario a aplicaciones de terceros, con credenciales específicas para esa aplicación de terceros. Además, el alcance del acceso también será específico para esa aplicación.

Para obtener información general sobre OAuth 1.0, consulta la guía de OAuth Core. En particular, consulta la sección 6. Autentica con OAuth. En OAuth 1.0 de tres segmentos completo, el proceso es el siguiente:

  1. La aplicación ("Consumidor") obtiene un token de solicitud.
  2. El usuario autoriza el token de solicitud.
  3. La aplicación intercambia el token de solicitud por un token de acceso.
  4. Para todas las solicitudes de recursos posteriores, el token de acceso se usa en una solicitud firmada.

Para que los servicios de terceros usen OAuth 1.0 sin interacción del usuario (por ejemplo, como lo requerirían los scripts de Google Ads), los pasos 1, 2 y 3 no son posibles. Por lo tanto, algunos servicios emiten un token de acceso desde su consola de configuración, lo que permite que la aplicación vaya directamente al paso 4. Esto se conoce como OAuth 1.0 de una sola etapa.

OAuth1

OAuth 1.0 en las secuencias de comandos de Google Ads

En el caso de los scripts de Google Ads, cada script suele interpretarse como una aplicación. A través de la consola o la página de configuración de administración del servicio, suele ser necesario lo siguiente:

  • Establece una configuración de aplicación para representar la secuencia de comandos.
  • Especifica qué permisos se extienden a la secuencia de comandos.
  • Obtén la clave de consumidor, el secreto de consumidor, el token de acceso y el secreto de acceso para usarlos con OAuth de una sola vía.

OAuth 2.0

OAuth 2.0 se usa en APIs populares para proporcionar acceso a los datos de los usuarios. El propietario de una cuenta de un servicio de terceros determinado otorga permiso a aplicaciones específicas para que accedan a los datos del usuario. Las ventajas son que el propietario puede hacer lo siguiente:

  • No tiene que compartir las credenciales de su cuenta con la aplicación.
  • Pueden controlar qué aplicaciones tienen acceso a los datos de forma individual y en qué medida. (Por ejemplo, el acceso otorgado puede ser de solo lectura o solo a un subconjunto de los datos).

Para usar servicios habilitados para OAuth 2.0 en los scripts de Google Ads, sigue estos pasos:

Fuera de tu guion

Otorga autorización para que los scripts de Google Ads accedan a tus datos de usuario a través de la API de terceros. En la mayoría de los casos, esto implicará configurar una aplicación en la consola del servicio de terceros. Esta aplicación representa tu secuencia de comandos.

Debes especificar qué derechos de acceso se deben otorgar a la aplicación de scripts de Google Ads y, por lo general, se le asignará un ID de cliente. Esto te permite, a través de OAuth 2.0, controlar qué aplicaciones tienen acceso a tus datos en el servicio de terceros y, también, qué aspectos de esos datos pueden ver o modificar.

En tu guion

Autoriza con el servidor remoto. Según el tipo de permiso que haya permitido el servidor, se deberá seguir un conjunto diferente de pasos, conocido como flujo, pero todos darán como resultado la emisión de un token de acceso que se usará para esa sesión en todas las solicitudes posteriores.

Realiza solicitudes a la API. Pasa el token de acceso con cada solicitud.

Flujos de autorización

Cada tipo de permiso y flujo correspondiente se adapta a diferentes situaciones de uso. Por ejemplo, se usa un flujo diferente cuando un usuario participa en una sesión interactiva, en contraste con una situación en la que se requiere que una aplicación se ejecute en segundo plano sin un usuario presente.

Los proveedores de APIs decidirán qué tipos de permisos aceptan, y esto guiará la forma en que el usuario procede con la integración de su API.

Implementación

Para todos los flujos de OAuth, el objetivo es obtener un token de acceso que, luego, se pueda usar durante el resto de la sesión para autenticar las solicitudes.

En una biblioteca de ejemplo, se ilustra cómo autenticar cada tipo de flujo diferente. Cada uno de estos métodos devuelve un objeto que obtiene y almacena el token de acceso, y facilita las solicitudes autenticadas.

El patrón de uso general es el siguiente:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

Otorgamiento de credenciales de cliente

El [otorgamiento de credenciales de cliente][client-credentials-rfc] es una de las formas más simples del flujo de OAuth2, en la que la aplicación intercambia un ID y un secreto, únicos para la aplicación, a cambio de la emisión de un token de acceso con límite de tiempo.

Credencial de cliente

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

Otorgamiento de token de actualización

El otorgamiento de tokens de actualización es similar al otorgamiento de credenciales de cliente, ya que una solicitud al servidor devolverá un token de acceso que se puede usar en la sesión.

Token de actualización

Obtén un token de actualización

La diferencia con el otorgamiento de token de actualización es que, mientras que los detalles necesarios para un otorgamiento de credenciales de cliente provienen de la configuración de la aplicación (por ejemplo, en el panel de control del servicio), el token de actualización se otorga como parte de un flujo más complejo, como un [otorgamiento de código de autorización][authorization-code-rfc], que requerirá la interacción del usuario:

Código de autorización

Usa OAuth Playground para obtener un token de actualización

OAuth2 Playground proporciona una IU que permite al usuario avanzar por el otorgamiento del código de autorización para obtener un token de actualización.

El botón de configuración en la parte superior derecha te permite definir todos los parámetros que se usarán en el flujo de OAuth, incluidos los siguientes:

  • Extremo de autorización: Se usa como el inicio del flujo de autorización.
  • Extremo de token: Se usa con el token de actualización para obtener un token de acceso.
  • ID de cliente y secreto: Son las credenciales de la aplicación.

    OAuth Playground

Uso de tokens de actualización

Una vez que se realiza la autorización inicial, los servicios pueden emitir un token de actualización, que luego se puede usar de manera similar al flujo de credenciales del cliente:

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Ejemplo de Search Ads 360

Search Ads 360 es un ejemplo de una API que se puede usar con un token de actualización. En este ejemplo, una secuencia de comandos genera y devuelve un informe. Consulta la referencia de la API de Search Ads 360 para obtener todos los detalles de otras acciones que se pueden realizar.

Crea la secuencia de comandos
  1. Crea un proyecto nuevo en la consola de Google Cloud y obtén un ID de cliente, un secreto de cliente y un token de actualización siguiendo el procedimiento de la guía de Search Ads 360. Asegúrate de habilitar la API de Search Ads 360.
  2. Pega la [secuencia de comandos de ejemplo][search-ads-360-example] en una secuencia de comandos nueva en Google Ads.
  3. Pega la [biblioteca de OAuth2 de ejemplo][oauth20-library-example] debajo de la lista de códigos.
  4. Modifica la secuencia de comandos para que contenga los valores correctos del ID de cliente, el secreto de cliente y el token de actualización.

Ejemplo de la API de Apps Script Execution

En este ejemplo, se ilustra cómo ejecutar una función en Apps Script con la API de Apps Script Execution. Esto te permite llamar a Apps Script desde los scripts de Google Ads.

Crea una secuencia de comandos de Apps Script

Crea una nueva secuencia de comandos. En el siguiente ejemplo, se mostrarán 10 archivos de Drive:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Configura Apps Script para la ejecución
  1. Guarda la secuencia de comandos.
  2. Haz clic en Recursos > Proyecto de Cloud Platform.
  3. Haz clic en el nombre del proyecto para navegar a la consola de Google Cloud.
  4. Navega a APIs y servicios.
  5. Habilita las APIs adecuadas, en este caso, la API de Drive y la API de ejecución de Apps Script.
  6. Crea credenciales de OAuth desde el elemento Credenciales del menú.
  7. De vuelta en tu secuencia de comandos, publícala para que se ejecute desde Publicar > Implementar como ejecutable de API.
Crea la secuencia de comandos de Google Ads
  1. Pega la secuencia de comandos de ejemplo en una secuencia de comandos nueva en Google Ads.
  2. Además, pega la [biblioteca de OAuth2 de ejemplo][oauth20-library-example] debajo de la lista de códigos.
  3. Modifica la secuencia de comandos para que contenga los valores correctos del ID de cliente, el secreto de cliente y el token de actualización.

Cuentas de servicio

Una alternativa a los tipos de permisos es el concepto de cuentas de servicio.

Las cuentas de servicio difieren de los tipos de permisos en que no se usan para acceder a los datos de los usuarios: Después de la autenticación, la cuenta de servicio realiza las solicitudes en nombre de la aplicación, no como el usuario que puede ser propietario del proyecto. Por ejemplo, si la cuenta de servicio usara la API de Drive para crear un archivo, este pertenecería a la cuenta de servicio y, de forma predeterminada, el propietario del proyecto no podría acceder a él.

Ejemplo de la API de Natural Language de Google

La [API de Natural Language][natural-language-api-docs] proporciona [análisis de sentimiento][sentiment-analysis-api-docs] y [análisis de entidades][entity-analysis-api-docs] para texto.

En este ejemplo, se ilustra el cálculo del [opinión][sentiment-api-docs] para el texto del anuncio, incluidos el título o la descripción. Esto proporciona una medida de lo positivo que es el mensaje y su magnitud: ¿Qué es mejor, Vendemos pasteles o Vendemos los mejores pasteles de Londres? Compra ahora.?

Configura la secuencia de comandos
  1. Crea un proyecto nuevo en la consola de Google Cloud.
  2. Habilita la [API de Natural Language][natural-language-api].
  3. Habilita la facturación para el proyecto.
  4. [Crea una cuenta de servicio][create-service-account]. Descarga el archivo JSON de credenciales.
  5. Pega la [secuencia de comandos de ejemplo][natural-language-example] en una secuencia de comandos nueva en Google Ads.
  6. Además, pega la [biblioteca de OAuth2 de ejemplo][oauth20-library-example] debajo de la lista de códigos.
  7. Reemplaza los valores necesarios:
    • serviceAccount: Es la dirección de correo electrónico de la cuenta de servicio, por ejemplo, xxxxx@yyyy.iam.gserviceaccount.com.
    • key: Es la clave del archivo JSON que se descargó cuando se creó la cuenta de servicio. Comienza el -----BEGIN PRIVATE KEY... y termina el ...END PRIVATE KEY-----\n.

Respuestas de la API

Las APIs pueden devolver datos en una variedad de formatos. Los más destacados son XML y JSON.

JSON

Por lo general, JSON es más simple que XML para trabajar como formato de respuesta. Sin embargo, aún pueden surgir algunos problemas.

Validación de respuesta

Una vez que obtengas una respuesta correcta de la llamada a la API, el siguiente paso habitual es usar JSON.parse para convertir la cadena JSON en un objeto de JavaScript. En este punto, es razonable controlar el caso en el que el análisis falla:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

Además, si la API no está bajo tu control, ten en cuenta que la estructura de la respuesta puede cambiar y que las propiedades pueden dejar de existir:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

XmlService permite que tus secuencias de comandos analicen y extraigan datos de los cuerpos de respuesta XML.

Validación

XML sigue siendo un formato popular para compilar APIs. Una respuesta de una llamada a la API se puede analizar con el método parse de XmlService:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

Si bien XmlService.parse detecta errores en el XML y arroja excepciones según corresponda, no proporciona la capacidad de validar el XML con un esquema.

Elemento raíz

Si el análisis del documento XML se realiza correctamente, el elemento raíz se obtiene con el método getRootElement():

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

Espacios de nombres

En el siguiente ejemplo, se usa la API de Sportradar para obtener los resultados de fútbol de los partidos seleccionados. La respuesta XML tiene el siguiente formato:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

Observa cómo se especifica el espacio de nombres en el elemento raíz. Por este motivo, es necesario hacer lo siguiente:

  • Extrae el atributo de espacio de nombres del documento.
  • Usa este espacio de nombres cuando recorras y accedas a elementos secundarios.

En el siguiente ejemplo, se muestra cómo acceder al elemento <schedule> y buscar sus elementos secundarios <sport_event> en el fragmento de documento anterior:

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

Obtener valores

Dada la muestra del programa de fútbol:

<sport_event_status status="..." ... />

Los atributos se pueden recuperar, por ejemplo:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

El texto que contiene un elemento se puede leer con getText(), pero se concatenará cuando haya varios elementos secundarios de texto de un elemento. Considera usar getChildren() y realizar iteraciones en cada elemento secundario en los casos en que es probable que haya varios elementos secundarios de texto.

Ejemplo de Sportradar

Este ejemplo completo de Sportradar ilustra la recuperación de detalles de partidos de fútbol, específicamente de la Premier League inglesa. La API de Soccer es uno de los muchos feeds de deportes que ofrece Sportradar.

Configura una cuenta de Sportradar
  1. Navega al sitio para desarrolladores de Sportradar.
  2. Regístrate para obtener una cuenta de prueba.
  3. Una vez que te hayas registrado, accede a tu cuenta.
  4. Una vez que accedas, navega a Mi cuenta.

Sportradar separa los diferentes deportes en distintas APIs. Por ejemplo, puedes comprar acceso a la API de fútbol, pero no a la de tenis. Cada aplicación que crees puede tener diferentes deportes asociados y diferentes claves.

  1. En Aplicaciones, haz clic en Crear una aplicación nueva. Asigna un nombre y una descripción a la aplicación, y omite el campo del sitio web.
  2. Selecciona solo Emitir una clave nueva para Soccer Trial Europe v2.
  3. Haz clic en Registrar aplicación.

Una vez que se complete correctamente, debería aparecer una página con tu nueva clave de API.

  1. Pega la secuencia de comandos de ejemplo en una secuencia de comandos nueva en Google Ads.
  2. Reemplaza la clave de API en la ficha por la clave recién emitida y edita el campo de la dirección de correo electrónico.

Solución de problemas

Cuando se trabaja con APIs de terceros, pueden producirse errores por varios motivos, por ejemplo:

  • Clientes que emiten solicitudes al servidor en un formato que la API no espera
  • Clientes que esperan un formato de respuesta diferente al que se encontró
  • Clientes que usan tokens o claves no válidos, o valores que se dejaron como marcadores de posición
  • Clientes que alcanzan los límites de uso
  • Clientes que proporcionan parámetros no válidos

En todos estos casos, y en otros, un buen primer paso para identificar la causa del problema es examinar los detalles de la respuesta que causa el error.

Analiza las respuestas

De forma predeterminada, el motor de secuencias de comandos de Google Ads arrojará cualquier respuesta que devuelva un error (un código de estado de 400 o superior).

Para evitar este comportamiento y permitir que se inspeccionen el error y el mensaje de error, establece la propiedad muteHttpExceptions de los parámetros opcionales en UrlFetchApp.fetch. Por ejemplo:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

Códigos de estado comunes

  • 200 OK indica que se realizó correctamente. Si la respuesta no contiene los datos esperados, ten en cuenta lo siguiente:

    • Algunas APIs permiten especificar qué campos, formato de respuesta o ambos, se deben usar. Consulta la documentación de la API para obtener más detalles al respecto.
    • Una API puede tener varios recursos a los que se puede llamar. Consulta la documentación para determinar si puede ser más apropiado usar un recurso diferente y si este devolverá los datos que necesitas.
    • Es posible que la API haya cambiado desde que se escribió el código. Consulta la documentación o al desarrollador para obtener aclaraciones.
  • Por lo general, 400 Bad Request significa que hay un error en el formato o la estructura de la solicitud que se envió al servidor. Inspecciona la solicitud y compárala con las especificaciones de la API para asegurarte de que cumpla con las expectativas. Consulta Inspecciona las solicitudes para obtener detalles sobre cómo examinarlas.

  • 401 Unauthorized suele significar que se llama a la API sin proporcionar o realizar correctamente la autorización.

    • Si la API usa la autorización básica, asegúrate de que el encabezado Authorization se construya y se proporcione en la solicitud.
    • Si la API usa OAuth 2.0, asegúrate de que se haya obtenido el token de acceso y de que se proporcione como un token del portador.
    • En el caso de cualquier otra variación en la autorización, asegúrate de que se proporcionen las credenciales necesarias para la solicitud.
  • 403 Forbidden indica que el usuario no tiene permiso para el recurso que se solicita.

    • Asegúrate de que se hayan otorgado los permisos necesarios al usuario, por ejemplo, darle acceso a un archivo en una solicitud basada en archivos.
  • 404 Not Found significa que el recurso solicitado no existe.

    • Verifica que la URL que se usa para el endpoint de API sea correcta.
    • Si recuperas un recurso, verifica que exista el recurso al que se hace referencia (por ejemplo, si el archivo existe para una API basada en archivos).

Inspecciona las solicitudes

Inspeccionar las solicitudes es útil cuando las respuestas de la API indican que la solicitud tiene un formato incorrecto, por ejemplo, un código de estado 400. Para ayudar a examinar las solicitudes, UrlFetchApp tiene un método complementario para el método fetch(), llamado getRequest(url, params).

En lugar de enviar una solicitud al servidor, este método construye la solicitud que se habría enviado y, luego, la devuelve. Esto permite que el usuario inspeccione los elementos de la solicitud para asegurarse de que se vea correcta.

Por ejemplo, si los datos del formulario de tu solicitud constan de muchas cadenas concatenadas, el error puede estar en la función que creaste para generar esos datos del formulario. En su forma más simple:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

te permitirá inspeccionar los elementos de la solicitud.

Registra solicitudes y respuestas

Para ayudar con todo el proceso de inspección de solicitudes y respuestas a una API de terceros, se puede usar la siguiente función auxiliar como un reemplazo directo de UrlFetchApp.fetch() para registrar las solicitudes y las respuestas.

  1. Reemplaza todas las instancias de UrlFetchApp.fetch() en tu código por logUrlFetch().

  2. Agrega la siguiente función al final de tu secuencia de comandos.

    function logUrlFetch(url, opt_params) {
     const params = opt_params || {};
     params.muteHttpExceptions = true;
     const request = UrlFetchApp.getRequest(url, params);
     console.log('Request:       >>> ' + JSON.stringify(request));
     const response = UrlFetchApp.fetch(url, params);
     console.log('Response Code: <<< ' + response.getResponseCode());
     console.log('Response text: <<< ' + response.getContentText());
     if (response.getResponseCode() >= 400) {
       throw Error('Error in response: ' + response);
     }
     return response;
    }
    

Cuando ejecutas tu secuencia de comandos, los detalles de todas las solicitudes y respuestas se registran en la consola, lo que facilita la depuración.

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities