Cette page a été traduite par l'API Cloud Translation.

API tierces

Les scripts Google Ads offrent une fonctionnalité puissante : la possibilité d'intégrer des données et des services provenant d'API tierces.

Ce guide présente les concepts suivants qui peuvent vous aider à écrire des scripts pour vous connecter à d'autres services:

Envoyer des requêtes HTTP: découvrez comment utiliser UrlFetchApp pour accéder aux API externes.
Authentification: nous abordons certains scénarios d'authentification courants.
Analyser les réponses: comment traiter les données JSON et XML renvoyées.

Nous incluons également des exemples pour un certain nombre d'API populaires qui illustrent ces concepts.

Récupérer des données avec UrlFetchApp

UrlFetchApp fournit les fonctionnalités de base requises pour interagir avec les API tierces.

L'exemple suivant montre comment extraire des données météorologiques à partir de OpenWeatherMap. Nous avons choisi OpenWeatherMap en raison de son schéma d'autorisation et de son API relativement simples.

Envoyer une requête

La documentation OpenWeatherMap spécifie le format à utiliser pour demander la météo actuelle comme suit:

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

L'URL fournit notre premier exemple d'autorisation: le paramètre apikey est obligatoire, et la valeur est propre à chaque utilisateur. Cette clé est obtenue en vous inscrivant.

Une fois inscrit, vous pouvez envoyer une requête à l'aide de la clé comme suit:

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());

L'exécution de ce code génère une longue chaîne de texte JSON écrite dans la fenêtre de journalisation des scripts Google Ads.

L'étape suivante consiste à convertir ce format en un format pouvant être utilisé dans votre script.

Données JSON

De nombreuses API fournissent des réponses au format JSON. Il s'agit d'une sérialisation simple d'objets JavaScript, de sorte que les objets, les tableaux et les types de base puissent être représentés et transférés sous forme de chaînes.

Pour convertir une chaîne JSON (comme celle renvoyée par OpenWeatherMap) en objet JavaScript, utilisez la méthode JSON.parse intégrée. Poursuivez l'exemple ci-dessus:

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

La méthode JSON.parse convertit la chaîne en objet, qui possède une propriété name.

Pour en savoir plus sur l'utilisation des réponses de l'API dans différents formats, consultez la section Analyser les réponses.

Gestion des exceptions

La gestion des erreurs est un aspect important à prendre en compte lorsque vous utilisez des API tierces dans vos scripts, car elles changent souvent et génèrent des valeurs de réponse inattendues, par exemple:

L'URL ou les paramètres de l'API peuvent changer à votre insu.
Votre clé API (ou d'autres identifiants utilisateur) peut expirer.
Le format de la réponse peut changer sans préavis.

Codes d'état HTTP

En raison des réponses inattendues potentielles, vous devez inspecter le code d'état HTTP. Par défaut, UrlFetchApp génère une exception si un code d'erreur HTTP est rencontré. Pour modifier ce comportement, vous devez transmettre un paramètre facultatif, comme dans l'exemple suivant:

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();
}

Structure de la réponse

Lorsque des API tierces changent, les développeurs ne sont souvent pas immédiatement au courant des modifications susceptibles d'affecter leurs scripts. Par exemple, si la propriété name renvoyée dans l'exemple OpenWeatherMap est remplacée par locationName, les scripts qui utilisent cette propriété échoueront.

Pour cette raison, il peut être utile de vérifier si la structure renvoyée est conforme aux attentes, par exemple:

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

Données POST avec UrlFetchApp

L'exemple d'introduction avec OpenWeatherMap ne récupère que des données. En règle générale, les appels d'API qui ne modifient pas l'état sur le serveur distant utilisent la méthode HTTP GET.

La méthode GET est la méthode par défaut pour UrlFetchApp. Toutefois, certains appels d'API, tels que les appels à un service qui envoie des messages SMS, nécessiteront d'autres méthodes, telles que POST ou PUT.

Pour illustrer l'utilisation d'appels POST avec UrlFetchApp, l'exemple suivant montre l'intégration avec Slack, une application de messagerie collaborative, pour envoyer un message Slack aux utilisateurs et groupes Slack.

Configurer Slack

Dans ce guide, nous partons du principe que vous avez déjà créé un compte Slack.

Comme pour OpenWeatherMap dans l'exemple précédent, vous devez obtenir un jeton pour pouvoir envoyer des messages. Slack fournit une URL unique appelée webhook entrant qui vous permet d'envoyer des messages à votre équipe.

Configurez un webhook entrant en cliquant sur Add Incoming WebHooks Integration (Ajouter une intégration de webhooks entrants) et en suivant les instructions. Le processus doit émettre une URL à utiliser pour la messagerie.

Envoyer une requête POST

Une fois que vous avez configuré votre webhook entrant, l'envoi d'une requête POST nécessite simplement d'utiliser quelques propriétés supplémentaires dans le paramètre options transmis à UrlFetchApp.fetch:

method: comme indiqué, la valeur par défaut est GET, mais nous la remplaçons ici et la définissons sur POST.

payload: données à envoyer au serveur dans le cadre de la requête POST. Dans cet exemple, Slack attend un objet sérialisé au format JSON, comme décrit dans la documentation Slack. Pour ce faire, la méthode JSON.stringify est utilisée et Content-Type est défini sur 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);

Exemple Slack étendu

L'exemple ci-dessus montre le nombre minimal de messages entrants à activer dans Slack. Un exemple étendu illustre la création et l'envoi d'un rapport sur les performances des campagnes à un groupe, ainsi que certaines options de mise en forme et d'affichage.

Message entrant

Pour en savoir plus sur les messages Slack, consultez la section Mise en forme des messages dans la documentation Slack.

Données de formulaire

L'exemple ci-dessus montre comment utiliser une chaîne JSON comme propriété payload pour la requête POST.

En fonction du format de payload, UrlFetchApp adopte différentes approches pour créer la requête POST:

Lorsque payload est une chaîne, l'argument de chaîne est envoyé en tant que corps de la requête.
Lorsque payload est un objet, par exemple une carte de valeurs:
```
{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
```
Les paires clé/valeur sont converties en données de formulaire:
```
subject=Test&to=mail@example.com&body=Hello,+World!
```
L'en-tête Content-Type de la requête est également défini sur application/x-www-form-urlencoded.

Certaines API nécessitent l'utilisation de données de formulaire lors de l'envoi de requêtes POST. Il est donc utile de garder à l'esprit cette conversion automatique des objets JavaScript en données de formulaire.

Authentification HTTP de base

L'authentification de base HTTP est l'une des formes d'authentification les plus simples et est utilisée par de nombreuses API.

L'authentification est effectuée en joignant un nom d'utilisateur et un mot de passe encodés aux en-têtes HTTP de chaque requête.

Authentification HTTP de base

Créer une requête

Pour générer une requête authentifiée, procédez comme suit:

Formez la phrase de passe en accolant le nom d'utilisateur et le mot de passe avec une deux-points, par exemple username:password.
Encodez la phrase de passe au format Base64. Par exemple, username:password devient dXNlcm5hbWU6cGFzc3dvcmQ=.
Joignez un en-tête Authorization à la requête, au format Authorization: Basic <encoded passphrase>.

L'extrait de code suivant montre comment procéder dans les scripts 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);

Exemples d'authentification de base

La section Exemples de code contient deux exemples qui illustrent l'utilisation de l'authentification de base HTTP:

Plivo

Plivo est un service qui facilite l'envoi et la réception de messages SMS via son API. Cet exemple illustre l'envoi de messages.

Inscrivez-vous auprès de Plivo.
Collez l'exemple de script dans un nouveau script dans Google Ads.
Remplacez les valeurs PLIVO_ACCOUNT_AUTHID et PLIVO_ACCOUNT_AUTHTOKEN par celles du tableau de bord de gestion.
Insérez votre adresse e-mail comme indiqué dans le script pour recevoir des notifications d'erreurs.
Pour utiliser Plivo, vous devez acheter des numéros ou en ajouter au compte d'essai. Ajoutez des numéros de bac à sable pouvant être utilisés avec le compte d'essai.
Ajoutez le numéro qui apparaîtra en tant qu'expéditeur et le numéro du destinataire.
Remplacez PLIVO_SRC_PHONE_NUMBER dans le script par l'un des numéros de bac à sable que vous venez d'enregistrer. Il doit inclure le code pays international, par exemple 447777123456 pour un numéro au Royaume-Uni.

Twilio

Twilio est un autre service qui facilite l'envoi et la réception de messages SMS via son API. Cet exemple illustre l'envoi de messages.

Inscrivez-vous auprès de Twillio.
Collez l'exemple de script dans un nouveau script dans Google Ads.
Remplacez les valeurs TWILIO_ACCOUNT_SID et TWILIO_ACCOUNT_AUTHTOKEN par celles affichées sur la page de la console du compte.
Remplacez TWILIO_SRC_PHONE_NUMBER par le numéro du tableau de bord. Il s'agit du numéro autorisé par Twilio à envoyer des messages.

OAuth 1.0

De nombreux services populaires utilisent OAuth pour l'authentification. OAuth existe sous plusieurs formes et versions.

Alors qu'avec l'authentification de base HTTP, un utilisateur ne dispose que d'un seul nom d'utilisateur et d'un seul mot de passe, OAuth permet d'autoriser des applications tierces à accéder au compte et aux données d'un utilisateur, à l'aide d'identifiants spécifiques à cette application tierce. De plus, l'étendue de l'accès sera également spécifique à cette application.

Pour en savoir plus sur OAuth 1.0, consultez le guide OAuth Core. En particulier, consultez la section 6. Authentification avec OAuth Dans le protocole OAuth 1.0 à trois maillons complet, le processus se présente comme suit:

L'application ("Consommateur") obtient un jeton de requête.
L'utilisateur autorise le jeton de requête.
L'application échange le jeton de requête contre un jeton d'accès.
Pour toutes les requêtes de ressources ultérieures, le jeton d'accès est utilisé dans une requête signée.

Pour que les services tiers utilisent OAuth 1.0 sans interaction utilisateur (comme le nécessiteraient les scripts Google Ads), les étapes 1, 2 et 3 ne sont pas possibles. Par conséquent, certains services émettent un jeton d'accès à partir de leur console de configuration, ce qui permet à l'application d'accéder directement à l'étape 4. C'est ce qu'on appelle OAuth 1.0 à une seule jambe.

OAuth1

OAuth 1.0 dans les scripts Google Ads

Pour les scripts Google Ads, chaque script est généralement interprété comme une application. Sur la page des paramètres de la console/d'administration du service, vous devez généralement:

Configurez une configuration d'application pour représenter le script.
Spécifiez les autorisations accordées au script.
Obtenez la clé client, le secret client, le jeton d'accès et le secret d'accès à utiliser avec OAuth à une seule extrémité.

OAuth 2.0

OAuth 2.0 est utilisé dans les API populaires pour fournir un accès aux données utilisateur. Le propriétaire d'un compte pour un service tiers donné accorde une autorisation à des applications spécifiques pour leur permettre d'accéder aux données utilisateur. Les avantages sont les suivants:

Ne doit pas partager ses identifiants de compte avec l'application.
Peut contrôler individuellement les applications qui ont accès aux données et dans quelle mesure. (par exemple, l'accès accordé peut être en lecture seule ou limité à un sous-ensemble de données).

Pour utiliser des services compatibles avec OAuth 2.0 dans les scripts Google Ads, procédez comme suit:

En dehors de votre script

Autorisez les scripts Google Ads à accéder à vos données utilisateur via l'API tierce. Dans la plupart des cas, vous devrez configurer une application dans la console du service tiers. Cette application représente votre script Google Ads.

Vous spécifiez les droits d'accès que l'application du script Google Ads doit recevoir. Un ID client lui est généralement attribué. Cela vous permet, via OAuth 2, de contrôler les applications qui ont accès à vos données dans le service tiers, ainsi que les aspects de ces données qu'elles peuvent voir ou modifier.

Dans votre script

Autoriser avec le serveur distant Selon le type d'autorisation autorisé par le serveur, un ensemble d'étapes différent, appelé flux, doit être suivi. Toutefois, un jeton d'accès sera toujours émis et utilisé pour cette session pour toutes les requêtes ultérieures.

Effectuer des requêtes API Transmettez le jeton d'accès avec chaque requête.

Flux d'autorisation

Chaque type d'autorisation et le flux correspondant répondent à différents scénarios d'utilisation. Par exemple, un flux différent est utilisé lorsqu'un utilisateur participe à une session interactive, contrairement à un scénario où une application doit s'exécuter en arrière-plan sans utilisateur.

Les fournisseurs d'API décident des types d'autorisations qu'ils acceptent, ce qui guide l'utilisateur dans l'intégration de son API.

Implémentation

Pour tous les différents flux OAuth, l'objectif est d'obtenir un jeton d'accès qui peut ensuite être utilisé pour le reste de la session afin d'authentifier les requêtes.

Une bibliothèque d'exemples illustre comment s'authentifier pour chaque type de flux. Chacune de ces méthodes renvoie un objet qui obtient et stocke le jeton d'accès, et facilite les requêtes authentifiées.

Le modèle d'utilisation général est le suivant:

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

Attribution des identifiants client

L'octroi d'identifiants client est l'une des formes les plus simples du flux OAuth2, dans lequel l'application échange un ID et un secret, propres à l'application, en échange de l'émission d'un jeton d'accès limité dans le temps.

Identifiants client

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

Autorisation de jeton d'actualisation

L'octroi du jeton d'actualisation est semblable à l'octroi des identifiants client, dans la mesure où une simple requête au serveur renvoie un jeton d'accès pouvant être utilisé dans la session.

Jeton d'actualisation

Obtenir un jeton d'actualisation

La différence avec l'octroi de jeton d'actualisation est que, tandis que les informations requises pour l'octroi d'identifiants client proviennent de la configuration de l'application (par exemple, dans le panneau de configuration du service), le jeton d'actualisation est accordé dans le cadre d'un flux plus complexe, tel qu'un octroi de code d'autorisation, qui nécessitera une interaction de l'utilisateur:

Code d'autorisation

Utiliser OAuth Playground pour obtenir un jeton d'actualisation

OAuth2 Playground fournit une UI qui permet à l'utilisateur de suivre l'octroi du code d'autorisation pour obtenir un jeton d'actualisation.

Le bouton Paramètres en haut à droite vous permet de définir tous les paramètres à utiliser dans le flux OAuth, y compris:

Point de terminaison d'autorisation: point de départ du flux d'autorisation.
Point de terminaison de jeton: utilisé avec le jeton d'actualisation pour obtenir un jeton d'accès.
ID client et secret: identifiants de l'application.

OAuth Playground

Obtenir un jeton d'actualisation à l'aide d'un script

Une autre méthode basée sur un script pour effectuer le flux est disponible dans l'exemple de génération de jetons d'actualisation.

Utilisation du jeton d'actualisation

Une fois l'autorisation initiale effectuée, les services peuvent émettre un jeton de rafraîchissement qui peut ensuite être utilisé de manière similaire au flux d'identifiants client. Vous trouverez deux exemples ci-dessous:

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

Exemple Search Ads 360

Search Ads 360 est un exemple d'API pouvant être utilisée avec un jeton d'actualisation. Dans cet exemple, un script génère et renvoie un rapport. Consultez la documentation de référence de l'API Search Ads 360 pour en savoir plus sur les autres actions possibles.

Créer le script

Créez un projet dans la console API, puis obtenez un ID client, un secret client et un jeton d'actualisation en suivant la procédure décrite dans le guide DoubleClick, en veillant à activer l'API DoubleClick Search.
Collez l'exemple de script dans un nouveau script dans Google Ads.
Collez l'exemple de bibliothèque OAuth2 sous la liste de code.
Modifiez le script pour qu'il contienne les valeurs correctes pour l'ID client, le code secret du client et le jeton d'actualisation.

Exemple d'utilisation de l'API d'exécution d'un Apps Script

Cet exemple illustre l'exécution d'une fonction dans Apps Script à l'aide de l'API d'exécution d'un Apps Script. Cela permet d'appeler Apps Script à partir de scripts Google Ads.

Créer un script Apps Script

Créez un script. L'exemple suivant liste 10 fichiers 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;
}

Configurer Apps Script pour l'exécution

Enregistrez le script.
Cliquez sur Resources > Cloud Platform project (Ressources > Projet Cloud Platform).
Cliquez sur le nom du projet pour accéder à la console API.
Accédez à API et services.
Activez les API appropriées, dans ce cas l'API Drive et l'API d'exécution de script Apps.
Créez des identifiants OAuth à partir de l'élément Identifiants du menu.
Dans votre script, publiez-le pour l'exécution à partir de Publish > Deploy as API Executable (Publier > Déployer en tant qu'exécutable d'API).

Créer le script Google Ads

Collez l'exemple de script dans un nouveau script dans Google Ads.
Collez également l'exemple de bibliothèque OAuth2 sous la liste de code.
Modifiez le script pour qu'il contienne les valeurs correctes pour l'ID client, le code secret du client et le jeton d'actualisation.

Comptes de service

Le concept de comptes de service constitue une alternative aux types d'autorisations ci-dessus.

Les comptes de service diffèrent des éléments ci-dessus en ce sens qu'ils ne sont pas utilisés pour accéder aux données utilisateur: après l'authentification, les requêtes sont effectuées par le compte de service au nom de l'application, et non en tant qu'utilisateur propriétaire du projet. Par exemple, si le compte de service utilisait l'API Drive pour créer un fichier, celui-ci appartiendrait au compte de service et ne serait pas accessible par défaut au propriétaire du projet.

Exemple d'API Natural Language de Google

L'API Natural Language fournit une analyse des sentiments et une analyse des entités pour le texte.

Cet exemple illustre le calcul du sentiment pour le texte de l'annonce, y compris le titre ou la description. Cela permet de mesurer le niveau de positivité et l'ampleur du message : quelle option est la meilleure : Nous vendons des gâteaux ou Nous vendons les meilleurs gâteaux de Londres ? Achetez dès aujourd'hui ! ?

Configurer le script

Créer un projet dans la console API
Activer l'API Natural Language
Activez la facturation pour le projet.
Créez un compte de service. Téléchargez le fichier JSON des identifiants.
Collez l'exemple de script dans un nouveau script dans Google Ads.
Collez également l'exemple de bibliothèque OAuth2 sous la liste de code.
Remplacez les valeurs nécessaires :
- serviceAccount: adresse e-mail du compte de service, par exemple xxxxx@yyyy.iam.gserviceaccount.com.
- key: clé du fichier JSON téléchargé lors de la création du compte de service. Commence le -----BEGIN PRIVATE KEY... et se termine le ...END PRIVATE KEY-----\n.

Réponses d'API

Les API peuvent renvoyer des données dans différents formats. Les plus notables sont le XML et le JSON.

JSON

Le format JSON est généralement plus simple à utiliser que le format XML en tant que format de réponse. Toutefois, des problèmes peuvent toujours survenir.

Validation de réponse

Une fois que vous avez obtenu une réponse de l'appel de l'API, l'étape suivante consiste généralement à utiliser JSON.parse pour convertir la chaîne JSON en objet JavaScript. À ce stade, il est judicieux de gérer le cas où l'analyse échoue:

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

De plus, si vous ne contrôlez pas l'API, gardez à l'esprit que la structure de la réponse peut changer et que les propriétés peuvent ne plus exister:

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

Validation

Le format XML reste populaire pour créer des API. Une réponse à partir d'un appel d'API peut être analysée à l'aide de la méthode XmlService parse:

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

Bien que XmlService.parse détecte les erreurs dans le fichier XML et génère des exceptions en conséquence, il n'est pas possible de valider le fichier XML à l'aide d'un schéma.

Élément racine

Une fois l'analyse du document XML terminée, l'élément racine est obtenu à l'aide de la méthode getRootElement():

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

Espaces de noms

Dans l'exemple suivant, l'API Sportradar est utilisée pour obtenir les résultats de matchs de football sélectionnés. La réponse XML se présente sous le format suivant:

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

Notez que l'espace de noms est spécifié dans l'élément racine. Par conséquent, vous devez:

Extrayez l'attribut d'espace de noms du document.
Utilisez cet espace de noms lorsque vous parcourez et accédez aux éléments enfants.

L'exemple suivant montre comment accéder à l'élément <matches> dans l'extrait de document ci-dessus:

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);

Obtenir des valeurs

Compte tenu de l'exemple de calendrier de football:

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

Vous pouvez récupérer des attributs, par exemple:

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

Le texte contenu dans un élément peut être lu à l'aide de getText(), mais il sera concaténé lorsqu'il y aura plusieurs enfants de texte d'un élément. Envisagez d'utiliser getChildren() et d'itérer sur chaque enfant dans les cas où plusieurs enfants de texte sont probables.

Exemple Sportradar

Cet exemple Sportradar complet illustre la récupération des détails des matchs de football, en particulier ceux de la Premier League anglaise. L'API Soccer fait partie d'un large éventail de flux sportifs proposés par Sportradar.

Configurer un compte Sportradar

Accédez au site pour les développeurs Sportradar.
Créez un compte d'essai.
Connectez-vous à votre compte.
Une fois connecté, accédez à MyAccount.

Sportradar sépare les différents sports en différentes API. Par exemple, vous pouvez acheter un accès à l'API de football, mais pas à l'API de tennis. Chaque application que vous créez peut être associée à différents sports et à différentes clés.

Sous "Applications", cliquez sur Créer une application. Attribuez un nom et une description à l'application, et ignorez le champ "Site Web".
Ne sélectionnez que l'option Émettre une nouvelle clé pour Soccer Trial Europe v2.
Cliquez sur Enregistrer l'application.

Une fois l'opération terminée, une page affichant votre nouvelle clé API devrait s'afficher.

Collez l'exemple de script dans un nouveau script dans Google Ads.
Remplacez la clé API dans la fiche par celle obtenue ci-dessus, puis modifiez le champ d'adresse e-mail.

Dépannage

Lorsque vous travaillez avec des API tierces, des erreurs peuvent se produire pour plusieurs raisons, par exemple:

Clients qui envoient des requêtes au serveur dans un format non attendu par l'API
Clients qui s'attendent à un format de réponse différent de celui rencontré
Clients utilisant des jetons ou des clés non valides, ou des valeurs laissées en tant qu'espaces réservés
Clients atteignant les limites d'utilisation
Clients fournissant des paramètres non valides.

Dans tous ces cas, et d'autres, une bonne première étape pour identifier l'origine du problème consiste à examiner les détails de la réponse à l'origine de l'erreur.

Analyser les réponses

Par défaut, toute réponse renvoyant une erreur (un code d'état de 400 ou plus) est générée par le moteur de scripts Google Ads.

Pour éviter ce comportement et permettre l'inspection de l'erreur et du message d'erreur, définissez la propriété muteHttpExceptions des paramètres facultatifs sur UrlFetchApp.fetch. Exemple :

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

Codes d'état courants

200 OK indique un succès. Si la réponse ne contient pas les données attendues, tenez compte des points suivants:
- Certaines API permettent de spécifier les champs et/ou le format de réponse à utiliser. Pour en savoir plus, consultez la documentation de l'API.
- Une API peut avoir plusieurs ressources pouvant être appelées. Consultez la documentation pour déterminer si une autre ressource peut être plus appropriée et renvoyer les données dont vous avez besoin.
- L'API a peut-être changé depuis la rédaction du code. Consultez la documentation ou le développeur pour obtenir des précisions.
400 Bad Request signifie généralement qu'un élément du formatage ou de la structure de la requête envoyée au serveur n'est pas correct. Inspectez la requête et comparez-la aux spécifications de l'API pour vous assurer qu'elle est conforme aux attentes. Pour savoir comment examiner les requêtes, consultez Inspecter les requêtes.
401 Unauthorized signifie généralement que l'API est appelée sans fournir d'autorisation ou sans l'effectuer correctement.
- Si l'API utilise l'autorisation de base, assurez-vous que l'en-tête Authorization est créé et fourni dans la requête.
- Si l'API utilise OAuth 2.0, assurez-vous que le jeton d'accès a été obtenu et qu'il est fourni en tant que jeton de support.
- Pour toute autre variation d'autorisation, assurez-vous de fournir les identifiants nécessaires à la requête.
403 Forbidden indique que l'utilisateur n'est pas autorisé à accéder à la ressource demandée.
- Assurez-vous que l'utilisateur a reçu les autorisations nécessaires, par exemple en lui donnant accès à un fichier dans une requête basée sur des fichiers.
404 Not Found signifie que la ressource demandée n'existe pas.
- Vérifiez que l'URL utilisée pour le point de terminaison de l'API est correcte.
- Si vous récupérez une ressource, vérifiez qu'elle existe (par exemple, si le fichier existe pour une API basée sur des fichiers).

Inspecter les requêtes

L'inspection des requêtes est utile lorsque les réponses de l'API indiquent que la requête est mal formée, par exemple avec un code d'état 400. Pour faciliter l'examen des requêtes, UrlFetchApp dispose d'une méthode associée à la méthode fetch(), appelée getRequest().

Au lieu d'envoyer une requête au serveur, cette méthode construit la requête qui aurait été envoyée, puis la renvoie. Cela permet à l'utilisateur d'inspecter les éléments de la requête pour s'assurer qu'elle semble correcte.

Par exemple, si les données du formulaire de votre requête se composent de nombreuses chaînes concatenatées, l'erreur peut se trouver dans la fonction que vous avez créée pour générer ces données de formulaire. En termes simples:

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

vous permet d'inspecter les éléments de la requête.

Journaliser les requêtes et les réponses

Pour faciliter l'ensemble du processus d'inspection des requêtes et des réponses à une API tierce, la fonction d'assistance suivante peut être utilisée comme remplacement de UrlFetchApp.fetch(), pour consigner à la fois les requêtes et les réponses.

Remplacez toutes les instances de UrlFetchApp.fetch() dans votre code par logUrlFetch().

Ajoutez la fonction suivante à la fin de votre script.

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;
}

Lorsque vous exécutez votre script, les détails de toutes les requêtes et réponses sont consignés dans la console, ce qui facilite le débogage.