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

API tierces

L'une des principales fonctionnalités des scripts Google Ads est leur capacité à intégrer des données et des services provenant d'API tierces.

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

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

Extraire des données avec UrlFetchApp

UrlFetchApp fournit la fonctionnalité de base requise pour interagir avec des API tierces.

L'exemple suivant montre comment récupérer des données météorologiques à partir d'OpenWeatherMap. Nous avons choisi OpenWeatherMap pour la simplicité de son système d'autorisation et de son API.

Envoyer une requête

La documentation d'OpenWeatherMap spécifie le format de demande de 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 sa valeur est propre à chaque utilisateur. Cette clé est obtenue lors de votre inscription.

Une fois inscrit, vous pouvez envoyer une demande à 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 entraîne l'écriture d'une longue chaîne de texte JSON dans la fenêtre de journalisation dans les scripts Google Ads.

L'étape suivante consiste à le convertir dans 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 simple sérialisation 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 reconvertir une chaîne JSON (comme celle renvoyée par OpenWeatherMap) en objet JavaScript, utilisez la méthode JSON.parse intégrée. Reprenons 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 d'API dans différents formats, consultez la section Analyser les réponses.

Gestion des exceptions

La gestion des erreurs est un élément important à prendre en compte lorsque vous utilisez des API tierces dans vos scripts, car celles-ci changent souvent fréquemment 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 du risque de réponses inattendues, 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 des réponses

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

Exemple d'introduction avec OpenWeatherMap, uniquement pour les données extraites En règle générale, les appels d'API qui ne changent pas d'é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 SMS, nécessitent d'autres méthodes, telles que POST ou PUT.

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

Configurer Slack

Ce guide suppose que vous êtes déjà inscrit à un compte Slack.

Comme pour OpenWeatherMap dans l'exemple précédent, il est nécessaire d'obtenir un jeton pour activer l'envoi de messages. Slack fournit une URL unique vous permettant d'envoyer des messages à votre équipe, appelée Webhook entrant.

Configurez un webhook entrant en cliquant sur Ajouter une intégration de webhooks entrants et en suivant les instructions. Le processus doit générer une URL à utiliser pour l'envoi de messages.

Envoyer une requête POST

Une fois votre webhook entrant configuré, une requête POST nécessite simplement l'utilisation de certaines propriétés supplémentaires dans le paramètre options transmis à UrlFetchApp.fetch:

method: comme indiqué, la valeur par défaut est GET, mais ici, nous l'ignorons et la définissons sur POST.

payload: il s'agit des 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 le 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 d'extension Slack

L'exemple ci-dessus indique le minimum à activer pour les messages entrants dans Slack. Un exemple étendu illustre la création d'un rapport sur les performances des campagnes et son envoi à 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 illustre l'utilisation d'une chaîne JSON comme propriété payload pour la requête POST.

Selon le format de payload, UrlFetchApp adopte différentes approches pour construire 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 un mappage de valeurs:
```
{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
```
Les paires clé/valeur sont converties en données form:
```
subject=Test&to=mail@example.com&body=Hello,+World!
```
De plus, l'en-tête Content-Type de la requête est 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 de base HTTP

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 réalisée en associant un nom d'utilisateur et un mot de passe encodés aux en-têtes HTTP de chaque requête.

Authentification de base HTTP

Créer une requête

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

Pour former la phrase secrète, associez le nom d'utilisateur et le mot de passe par deux-points (par exemple, username:password).
Encodez la phrase secrète en 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);

Plivo

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

S'inscrire auprès de Plivo
Collez l'exemple de script dans un nouveau script Google Ads.
Remplacez les valeurs PLIVO_ACCOUNT_AUTHID et PLIVO_ACCOUNT_AUTHTOKEN par les valeurs du tableau de bord de gestion.
Insérez votre adresse e-mail comme indiqué dans le script pour la notification des erreurs.
Pour utiliser Plivo, vous devez acheter des numéros ou en ajouter au compte d'essai. Ajoutez les numéros de bac à sable pouvant être utilisés avec le compte d'essai.
Ajoutez le numéro qui apparaîtra comme expéditeur et le numéro du destinataire.
Mettez à jour PLIVO_SRC_PHONE_NUMBER dans le script avec l'un des numéros de bac à sable récemment enregistrés. Il doit inclure le code pays international, par exemple 447777123456 pour un numéro britannique.

Twilio

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

S'inscrire 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 les valeurs affichées sur la page de la console du compte.
Remplacez TWILIO_SRC_PHONE_NUMBER par le numéro indiqué dans le tableau de bord, c'est-à-dire le numéro autorisé par Twilio à envoyer des messages.

OAuth 1.0

De nombreux services courants utilisent OAuth pour l'authentification. OAuth est disponible sous différentes versions et versions.

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

Pour plus d'informations sur OAuth 1.0, consultez le guide OAuth Core. Consultez en particulier la section 6. Authentification avec OAuth. Avec le protocole OAuth 1.0 à trois acteurs complet, le processus est le suivant:

L'application ("Consommateur") obtient un jeton de requête.
L'utilisateur autorise le jeton de demande.
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 des services tiers utilisent OAuth 1.0 sans interaction de l'utilisateur (comme l'exigeraient 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 l'authentification OAuth 1.0 à une étape.

OAuth1

OAuth 1.0 dans les scripts Google Ads

Dans les scripts Google Ads, chaque script est généralement interprété comme une application. Via la page des paramètres de la console/d'administration du service, il est généralement nécessaire d'effectuer les opérations suivantes:

Établir une configuration d'application pour représenter le script.
Spécifiez les autorisations qui sont étendues au script.
Obtenez la clé client, le code secret client, le jeton d'accès et le code secret d'accès à utiliser avec l'authentification OAuth à un rôle.

OAuth 2.0

OAuth 2.0 est utilisé dans les API populaires pour fournir l'accès aux données utilisateur. Le propriétaire d'un compte pour un service tiers donné accorde l'autorisation à des applications spécifiques d'accéder aux données utilisateur. L'avantage est que le propriétaire:

n'a pas besoin de partager les identifiants de leur compte avec l'application ;
Peut contrôler quelles applications ont accès aux données de manière individuelle et dans quelle mesure. Par exemple, l'accès accordé peut être en lecture seule ou seulement pour un sous-ensemble de données.

Pour utiliser les services 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, il s'agira de 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 devant être accordés à l'application Google Ads Script. Un ID client lui sera 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 consulter ou modifier.

Dans votre script

Accorder l'autorisation avec le serveur distant : Selon le type d'autorisation autorisé par le serveur, un autre ensemble d'étapes, appelé flux, doit être suivi, mais toutes ces étapes entraînent l'émission d'un jeton d'accès qui est utilisé pour cette session pour toutes les requêtes ultérieures.

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

Flux d'autorisation

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

Les fournisseurs d'API décident des types d'autorisations qu'ils acceptent, ce qui explique comment l'utilisateur procède à 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 pourra ensuite être utilisé pendant le reste de la session pour authentifier les requêtes.

Une bibliothèque d'exemples montre 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);

Octroi des identifiants client

L'attribution d'identifiants client est l'une des formes les plus simples du flux OAuth2, dans laquelle l'application échange un ID et un code secret spécifiques à l'application en échange de l'émission d'un jeton d'accès à durée limitée.

Identifiant 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

Octroi du jeton d'actualisation

L'attribution du jeton d'actualisation est semblable à l'attribution 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'attribution du jeton d'actualisation est que, bien que les détails requis pour l'attribution 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'une attribution de code d'autorisation, qui nécessite une interaction de l'utilisateur:

Code d'autorisation

Utiliser OAuth Playground pour obtenir un jeton d'actualisation

OAuth2 Playground fournit une interface utilisateur qui permet à l'utilisateur de suivre la procédure d'attribution du code d'autorisation pour obtenir un jeton d'actualisation.

Le bouton des 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: utilisé comme début du flux d'autorisation.
Point de terminaison du jeton: utilisé avec le jeton d'actualisation pour obtenir un jeton d'accès.
ID client et code secret: identifiants de l'application.

OAuth Playground

Utiliser un script pour obtenir un jeton d'actualisation

Une alternative basée sur un script à l'achèvement du flux est disponible dans l'exemple de génération de jetons d'actualisation.

Actualiser l'utilisation des jetons

Une fois l'autorisation initiale effectuée, les services peuvent émettre un jeton d'actualisation qui peut ensuite être utilisé de la même manière que le flux d'identifiants client. Voici deux exemples:

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. Pour en savoir plus sur les autres actions que vous pouvez effectuer, consultez la documentation de référence de l'API Search Ads 360.

Créer le script

Créez un projet dans la console API, puis obtenez un ID client, un code secret du 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 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'API Apps Script Execution

Cet exemple montre comment exécuter une fonction dans Apps Script à l'aide de l'API Apps Script Execution. Cela permet d'appeler Apps Script à partir des scripts Google Ads.

Créer un script Apps Script

Créez un script. L'exemple suivant répertorie 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 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 Apps Script Execution.
Créez des identifiants OAuth à partir de l'élément Credentials (Identifiants) du menu.
De retour dans votre script, publiez le script pour exécution depuis 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 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

Une alternative aux types d'attribution ci-dessus est le concept de comptes de service.

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

Exemple d'API Google Natural Language

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 du texte d'annonce, y compris le titre ou la description. Cette valeur permet de mesurer le degré de satisfaction et l'ampleur du message: à savoir, Nous vendons des gâteaux ou Nous vendons les meilleurs gâteaux de Paris. Acheter aujourd'hui !?

Configurer le script

Créez un projet dans la console API.
Activez l'API Natural Language.
Activez la facturation pour le projet.
Créez un compte de service. Téléchargez le fichier JSON d'identifiants.
Collez l'exemple de script dans un nouveau script 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. XML et JSON sont les plus importants.

JSON

Le format de réponse JSON est généralement plus simple que XML. Toutefois, des problèmes peuvent encore survenir.

Validation de réponse

Après avoir obtenu une réponse positive 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, tenez compte du fait que la structure de la réponse peut changer et que les propriétés n'existent plus:

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

XML reste un format couramment utilisé pour créer des API. Une réponse 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 code XML et génère des exceptions en conséquence, il ne permet pas de valider le code XML par rapport à un schéma.

Élément racine

Si l'analyse du document XML a abouti, 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 football des matchs sélectionnés. La réponse XML prend 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. Pour cette raison, vous devez:

Extrayez l'attribut d'espace de noms du document.
Utilisez cet espace de noms pour parcourir les éléments enfants et y accéder.

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

D'après l'échantillon du calendrier des matchs de football:

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

Exemples de attributs pouvant être récupérés:

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

Le texte contenu dans un élément peut être lu à l'aide de getText(), mais ceux-ci seront concaténés lorsqu'il existe plusieurs enfants de texte d'un élément. Envisagez d'utiliser getChildren() et d'itérer pour chaque enfant si plusieurs enfants textuels sont susceptibles d'en avoir plusieurs.

Exemple Sportradar

Cet exemple complet de Sportradar illustre la récupération des informations sur les matchs de football, en particulier les matchs de la Premier League anglaise. L'API Soccer est l'un des nombreux 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.
Une fois inscrit, connectez-vous à votre compte.
Une fois connecté, accédez à MyAccount.

Sportradar distingue les différents sports en API distinctes. Par exemple, vous pouvez acheter l'accès à l'API Soccer, mais pas à l'API 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 du site Web.
Sélectionnez uniquement l'option Émettre une nouvelle clé pour l'essai de football Europe v2.
Cliquez sur Register Application (Enregistrer l'application).

Une fois l'opération réussie, une page contenant votre nouvelle clé API devrait s'afficher.

Collez l'exemple de script dans un nouveau script dans Google Ads.
Remplacez la clé API de la fiche par la clé 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:

Les 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 clés ou des jetons non valides, ou des valeurs conservées sous forme d'espaces réservés.
Clients atteignant les limites d'utilisation.
Clients fournissant des paramètres non valides.

Dans tous ces cas, entre autres, une bonne première étape pour identifier la cause 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 qui renvoie une erreur (un code d'état supérieur ou égal à 400) est générée par le moteur de scripts Google Ads.

Pour éviter ce comportement, et pour pouvoir inspecter l'erreur et le 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 une réussite. 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 comporter plusieurs ressources pouvant être appelées. Consultez la documentation pour déterminer si une autre ressource peut être plus appropriée et qu'elle renverra les données dont vous avez besoin.
- Il est possible que l'API ait été modifiée depuis que le code a été écrit. Pour plus d'informations, consultez la documentation ou contactez le développeur.
400 Bad Request signifie généralement que le format ou la structure de la requête envoyée au serveur est incorrect. Examinez la requête et comparez-la aux spécifications de l'API pour vous assurer qu'elle répond aux attentes. Pour savoir comment examiner les requêtes, consultez la section Inspecter les requêtes.
401 Unauthorized signifie généralement que l'API est appelée sans fournir ni exécuter d'autorisation.
- Si l'API utilise une 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 variante d'autorisation, assurez-vous de fournir les identifiants nécessaires à la requête.
403 Forbidden indique que l'utilisateur n'a pas l'autorisation d'accéder à la ressource demandée.
- Assurez-vous que l'utilisateur a reçu les autorisations nécessaires, par exemple pour lui donner 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 que la ressource référencée existe (par exemple, si le fichier existe pour une API basée sur des fichiers).

Inspecter les demandes

L'inspection des requêtes est utile lorsque les réponses de l'API indiquent qu'elles sont mal formées (par exemple, un code d'état 400). Pour vous aider à examiner les 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 de formulaire de votre requête sont composées de plusieurs chaînes concaténées, l'erreur peut résider dans la fonction que vous avez créée pour générer ces données de formulaire. Pour faire simple:

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

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

Consigner les requêtes et les réponses

Pour vous aider pendant l'intégralité du processus d'inspection des requêtes et des réponses à une API tierce, la fonction d'assistance suivante peut être utilisée en 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;
}

Lors de l'exécution de votre script, les détails de toutes les requêtes et réponses sont enregistrés dans la console, ce qui facilite le débogage.