API de terceros

Una función eficaz de las secuencias de comandos de Google Ads es la capacidad de integrarse con los datos y los servicios de las API 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: Abordamos algunas situaciones comunes de autenticación.
  • Análisis de respuestas: Cómo procesar los datos JSON y XML que se muestran.

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: se requiere el parámetro apikey y el valor es único para cada usuario. Esta clave se obtiene mediante el registro.

Después del registro, se puede 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 string larga de texto JSON que se escribe en la ventana de registro de las secuencias de comandos de Google Ads.

El siguiente paso es convertir esto a un formato que se pueda usar dentro de tu secuencia de comandos.

Datos JSON

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

Para convertir una string JSON (como la que se muestra en OpenWeatherMap) en un objeto JavaScript, usa el método integrado JSON.parse. 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 Respuestas de análisis para obtener más detalles sobre cómo trabajar con respuestas de la API en diferentes formatos.

Manejo de errores

El manejo de errores es una consideración importante cuando se trabaja con API de terceros en tus secuencias de comandos, ya que estas suelen cambiar con frecuencia y generan 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 alguna 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 respuestas inesperadas, debes inspeccionar el código de estado HTTP. Según la configuración 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, los desarrolladores no suelen estar al tanto de los cambios que podrían afectar sus 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');
}

Datos de POST con UrlFetchApp

En el ejemplo introductorio con OpenWeatherMap, solo se recuperan datos. Por lo general, las llamadas a la API que no cambian de 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 de POST con UrlFetchApp, en el siguiente ejemplo se demuestra 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 en 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 que te permite enviar mensajes a tu equipo, llamada webhook entrante.

Para configurar un webhook entrante, haz clic en Agregar integración de webhooks entrantes y sigue las instrucciones. El proceso debe emitir una URL para usar en la mensajería.

Realiza una solicitud POST

Una vez que configures el webhook entrante, realizar una solicitud POST simplemente requiere el uso de algunas propiedades adicionales en el parámetro options que se pasa a UrlFetchApp.fetch:

  • method: Como se mencionó, este valor predeterminado es GET, pero aquí lo anulamos y lo configuramos en POST.

  • payload: Estos son los datos que se enviarán al servidor como parte de la solicitud POST. 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 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 de Slack extendido

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

Mensaje entrante

Consulta formatos de mensajes en la documentación de Slack para obtener más detalles.

Datos de formulario

En el ejemplo anterior, se demostró el uso de una cadena JSON como la propiedad payload para la solicitud POST.

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

  • Cuando payload es una string, el argumento de string se envía como el cuerpo de la solicitud.

  • Cuando payload es un objeto (por ejemplo, un mapa de valores), sucede lo siguiente:

    {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 para 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 JavaScript a datos de formularios.

Autenticación básica HTTP

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

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

Autenticación básica HTTP

Crea una solicitud

Los siguientes pasos son necesarios para producir una solicitud autenticada:

  1. Crea la frase de contraseña uniendo el nombre de usuario y la contraseña con dos puntos, por ejemplo, username:password.
  2. La frase de contraseña se codifica 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 las secuencias de comandos 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);

Plivo

Plivo es un servicio que facilita el envío y la recepción de mensajes SMS a través de su API. En este ejemplo, se ilustra el envío de mensajes.

  1. Regístrate en Plivo.
  2. Pega la secuencia de comandos de muestra en una nueva secuencia de comandos de 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 la notificación 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 el remitente y el de 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. Esto 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 a través de su API. En este ejemplo, se ilustra el envío de mensajes.

  1. Regístrate en Twillio.
  2. Pega la secuencia de comandos de muestra en una nueva secuencia de comandos de Google Ads.
  3. Reemplaza los valores TWILIO_ACCOUNT_SID y TWILIO_ACCOUNT_AUTHTOKEN por los que se muestran en la página de la consola de cuentas.
  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 tiene una variedad de variantes y versiones.

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

Para obtener más información sobre OAuth 1.0, consulta la guía de OAuth Core. En particular, consulta 6. Autenticación con OAuth. En OAuth 1.0 completo de tres segmentos, 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, se usa el token de acceso en una solicitud firmada.

Para que los servicios de terceros utilicen OAuth 1.0 sin interacción del usuario (por ejemplo, como requerirían las secuencias de comandos 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 un solo segmento.

OAuth1

OAuth 1.0 en secuencias de comandos de Google Ads

En el caso de las secuencias de comandos de Google Ads, cada secuencia se suele interpretar como una aplicación. A través de la página de configuración de la consola o administración para el servicio, por lo general, es necesario hacer lo siguiente:

  • Establece una configuración de la aplicación para representar la secuencia de comandos.
  • Especifica los permisos que se extenderán 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 un solo segmento.

OAuth 2.0

Se usa OAuth 2.0 en las API populares para proporcionar acceso a los datos del usuario. El propietario de una cuenta para un servicio de terceros determinado otorga permiso a aplicaciones específicas para permitirles acceder a los datos del usuario. Las ventajas son que el propietario:

  • No tiene que compartir las credenciales de su cuenta con la aplicación.
  • Puede 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 datos).

Para utilizar los servicios habilitados para OAuth 2.0 en las secuencias de comandos de Google Ads, debes seguir varios pasos:

Fuera del guion

Otorga autorización para que las secuencias de comandos de Google Ads accedan a tus datos del 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 de Google Ads.

Tú especificas qué derechos de acceso debe otorgar la aplicación de secuencia de comandos de Google Ads y, por lo general, se le asignará un ID de cliente. Esto te permite controlar mediante OAuth 2 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 el guion

Autoriza con el servidor remoto. Según el tipo de otorgamiento que haya permitido el servidor, se seguirá un conjunto de pasos diferente, conocido como flujo, pero, en última instancia, todos generarán 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 otorgamiento y flujo correspondiente se adaptan a diferentes situaciones de uso. Por ejemplo, se usa un flujo diferente cuando un usuario participa en una sesión interactiva, a diferencia de una situación en la que se requiere que una aplicación se ejecute en segundo plano sin la presencia de un usuario.

Los proveedores de API decidirán qué tipos de otorgamiento aceptan, y esto guiará cómo el usuario procede con la integración de su API.

Implementación

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

Una biblioteca de muestra que ilustra cómo realizar la autenticación para cada tipo de flujo diferente. Cada uno de estos métodos muestra 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 es una de las formas más simples de flujo de OAuth2, en el 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 por tiempo limitado.

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

La concesión de un token de actualización es similar a la asignación de credenciales de cliente, ya que una solicitud simple al servidor muestra un token de acceso que puede usarse en la sesión.

Token de actualización

Cómo obtener un token de actualización

La diferencia con el otorgamiento del token de actualización es que, mientras que los detalles que se requieren para que un cliente otorgue credenciales 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, que requerirá la interacción del usuario:

Código de autorización

Usa el Playground de OAuth para obtener un token de actualización

La zona de pruebas de OAuth2 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 de la esquina superior derecha te permite definir todos los parámetros que quieres usar en el flujo de OAuth, incluidos los siguientes:

  • Extremo de autorización: Se usa como el inicio del flujo para la autorización.
  • Extremo del token: Se usa con el token de actualización para obtener un token de acceso.
  • client ID and secret: Credenciales para la aplicación.

Playground de OAuth

Cómo usar una secuencia de comandos para obtener un token de actualización

En el ejemplo de generación de tokens de actualización, se encuentra disponible una alternativa basada en secuencias de comandos para completar el flujo.

Actualizar el uso del token

Una vez realizada la autorización inicial, los servicios pueden emitir un token de actualización que se puede usar de manera similar al flujo de credenciales de cliente. A continuación, se proporcionan dos ejemplos:

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 esta muestra, una secuencia de comandos genera y muestra 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 API 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 DoubleClick, y asegúrate de habilitar la API de DoubleClick Search.
  2. Pega la secuencia de comandos de muestra en una secuencia de comandos nueva en Google Ads.
  3. Pega la biblioteca de OAuth2 de muestra debajo de la lista de código.
  4. Modifica la secuencia de comandos para que contenga los valores correctos del ID de cliente, el secreto del cliente y el token de actualización.

Ejemplo de la API de Apps Script Execution

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

Crear una secuencia de comandos de Apps Script

Crea una secuencia de comandos nueva. 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;
}
Configurar 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 API.
  4. Navega a APIs y servicios.
  5. Habilita las APIs adecuadas, en este caso la API de Drive y la API de Apps Script Execution.
  6. Crea credenciales de OAuth desde el elemento Credenciales en el menú.
  7. De vuelta en tu secuencia de comandos, publica la secuencia de comandos para su ejecución desde Publicar > Implementar como API ejecutable.
Crea la secuencia de comandos de Google Ads
  1. Pega la secuencia de comandos de muestra en una secuencia de comandos nueva en Google Ads.
  2. Además, pega la biblioteca de OAuth2 de muestra debajo de la lista de código.
  3. Modifica la secuencia de comandos para que contenga los valores correctos del ID de cliente, el secreto del cliente y el token de actualización.

Cuentas de servicio

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

Las cuentas de servicio difieren de lo anterior en que no se usan para acceder a los datos del usuario: 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 el 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, no sería accesible para el propietario del proyecto.

Ejemplo de la API de Natural Language

La API de Natural Language proporciona análisis de opiniones y análisis de entidades para texto.

En este ejemplo, se muestra cómo se calcula la opinión del texto del anuncio, incluidos el título o la descripción. Esto proporciona una medida de qué tan positivo es el mensaje y su magnitud: Cuál es mejor, Vendemos pasteles o Vendemos los mejores pasteles en Londres. Cómpralo hoy mismo?

Configura la secuencia de comandos
  1. Crea un proyecto nuevo en la Consola de API
  2. Habilitar la API de Natural Language
  3. Habilita la facturación para el proyecto.
  4. Crea una cuenta de servicio. Descarga el archivo JSON de credenciales.
  5. Pega la secuencia de comandos de muestra en una nueva secuencia de comandos de Google Ads.
  6. Además, pega la biblioteca de OAuth2 de muestra debajo de la lista de código.
  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 descargado cuando se crea la cuenta de servicio. Comienza el -----BEGIN PRIVATE KEY... y termina el ...END PRIVATE KEY-----\n.

Respuestas de la API

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

JSON

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

Validación de respuesta

Después de obtener una respuesta exitosa de la llamada a la API, el paso siguiente típico es usar JSON.parse para convertir la cadena JSON en un objeto de JavaScript. En este punto, es sensato 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 no puedes controlar la API, ten en cuenta que la estructura de la respuesta podría cambiar y que es posible que las propiedades ya no existan:

// 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

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 XmlService parse:

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 en consecuencia, no proporciona la capacidad de validar el XML en función de un esquema.

Elemento raíz

Si el documento XML se analiza correctamente, el elemento raíz se obtiene mediante 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 Spanner para obtener resultados de fútbol en los partidos seleccionados. La respuesta XML toma el siguiente formato:

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

Observa cómo se especifica el espacio de nombres en el elemento raíz. Debido a esto, debes hacer lo siguiente:

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

En el siguiente ejemplo, se muestra cómo acceder al elemento <matches> en el fragmento de documento anterior:

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

Obtén valores

Tomada la muestra del cronograma de fútbol:

<match status="..." category="..." ... >
  ...
</match>

Los atributos se pueden recuperar, por ejemplo:

const status = matchElement.getAttribute('status').getValue();

El texto dentro de un elemento se puede leer con getText(), pero estos se concatenarán cuando haya varios elementos secundarios de texto de un elemento. Considera usar getChildren() y, luego, iterar sobre cada elemento secundario en los casos en que sea probable que haya varios elementos secundarios de texto.

Ejemplo de Sportradar

En este ejemplo completo de Spanner, se ilustra la recuperación de detalles de partidos de fútbol, en especial, los partidos de la Premier League inglesa. La API de Soccer es uno de la amplia variedad de feeds de deportes que ofrece Sportradar.

Cómo configurar una cuenta de Sportradar
  1. Navega al sitio para desarrolladores de Spanner.
  2. Regístrate para obtener una cuenta de prueba.
  3. Una vez que te hayas registrado, accede a tu cuenta.
  4. Una vez que lo hagas, navega a MyAccount.

Sportradar separa diferentes deportes en diferentes APIs. Por ejemplo, puedes comprar acceso a la API de Soccer, pero no a la API de Tennis. Cada aplicación que creas puede tener diferentes deportes asociados y diferentes claves.

  1. En Aplicaciones, haz clic en Crear una aplicación nueva. Otorga un nombre y una descripción a la aplicación y, luego, ignora el campo del sitio web.
  2. Selecciona solo la opción Emitir una clave nueva para la prueba de fútbol europea v2.
  3. Haz clic en Registrar aplicación.

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

  1. Pega la secuencia de comandos de muestra en una nueva secuencia de comandos de Google Ads.
  2. Reemplaza la clave de API en la ficha por la clave que obtuviste antes y edita el campo de dirección de correo electrónico.

Solución de problemas

Cuando se trabaja con API de terceros, se pueden producir errores por varios motivos, como los siguientes:

  • Clientes que emiten solicitudes al servidor en un formato no esperado por la API.
  • Clientes que esperan un formato de respuesta diferente al que se encuentra.
  • Clientes que usan claves o tokens no válidos, o valores que quedan 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.

Cómo analizar respuestas

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

Para evitar este comportamiento y permitir que se inspeccionen el error y su mensaje, configura la propiedad muteHttpExceptions de los parámetros opcionales como 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 la prueba se realizó con éxito. Si la respuesta no contiene los datos esperados, considera lo siguiente:

    • Algunas APIs permiten especificar qué campos o formato de respuesta usar. Consulta la documentación de la API para obtener más detalles.
    • Una API puede tener múltiples recursos a los que se puede llamar. Consulta la documentación para determinar si un recurso diferente puede ser más apropiado para usar, y te mostrará los datos que necesitas.
    • Es posible que la API haya cambiado desde que se escribió el código. Consulta la documentación o el desarrollador para obtener una aclaración.

  • 400 Bad Request normalmente significa que algo no es correcto en el formato o la estructura de la solicitud enviada al servidor. Inspecciona la solicitud y compárala con las especificaciones de la API para asegurarte de que cumpla con las expectativas. Consulta Cómo inspeccionar solicitudes para obtener detalles sobre cómo examinarlas.

  • 401 Unauthorized generalmente significa que se llama a la API sin proporcionar la autorización o realizarla correctamente.

    • Si la API usa 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 el token de acceso se haya obtenido y de que se proporcione como un token del portador.
    • Para cualquier otra variación de 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 le hayan otorgado los permisos necesarios al usuario; por ejemplo, le otorga acceso a un archivo en una solicitud basada en archivos.

  • 404 Not Found significa que el recurso solicitado no existe.

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

Cómo inspeccionar solicitudes

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

En lugar de enviar una solicitud al servidor, este método construye la solicitud que podría haberse enviado y luego la muestra. De esta manera, el usuario puede inspeccionar elementos de la solicitud para garantizar que esta se vea correcta.

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

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

podrá inspeccionar los elementos de la solicitud.

Registrar 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 reemplazo directo de UrlFetchApp.fetch() a fin de registrar solicitudes y respuestas.

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

  2. Agrega la siguiente función al final de la 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 la secuencia de comandos, los detalles de todas las solicitudes y respuestas se registran en la consola, lo que facilita la depuración.