Les scripts Google Ads offrent une fonctionnalité puissante : l'intégration de données et de 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 : découvrez comment utiliser
UrlFetchApppour accéder à des 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 des API tierces.
L'exemple suivant montre comment récupérer des données météo à partir d'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 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 unique pour chaque utilisateur. Cette clé est obtenue en vous inscrivant.
Après l'inscription, une requête utilisant la clé peut être émise 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 ces données 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 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. En reprenant l'exemple précédent :
const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
// "London"
La méthode JSON.parse convertit la chaîne en un objet doté d'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 exceptions 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 un autre identifiant 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 de la réponse
Lorsque des API tierces sont modifiées, vous n'êtes pas forcément informé immédiatement des changements susceptibles d'affecter vos 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.
C'est pourquoi il peut être utile de vérifier si la structure renvoyée est celle attendue, 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érait 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 SMS, nécessitent d'autres méthodes, comme 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, pour envoyer un message Slack aux utilisateurs et aux groupes Slack.
Configurer Slack
Ce guide suppose 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 Ajouter l'intégration de webhooks entrants et en suivant les instructions. Le processus doit émettre une URL à utiliser pour la messagerie.
Effectuer une requête POST
Une fois que vous avez configuré votre webhook entrant, l'envoi d'une requête POST nécessite l'utilisation de propriétés supplémentaires dans le paramètre options transmis à UrlFetchApp.fetch :
method: comme indiqué, la valeur par défaut estGET, mais nous la remplaçons ici parPOST.payload: données à envoyer au serveur dans le cadre de la requêtePOST. 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][json-stringify-url] est utilisée etContent-Typeest défini surapplication/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 précédent montre le code minimal nécessaire pour activer les messages entrants dans Slack. Un exemple étendu illustre la création et l'envoi d'un rapport sur les performances d'une campagne à un groupe, ainsi que certaines options de mise en forme et d'affichage.

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 précédent 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
payloadest une chaîne, l'argument de chaîne est envoyé en tant que corps de la requête. Lorsque
payloadest 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 de formulaire :
subject=Test&to=mail@example.com&body=Hello,+World!De plus, l'en-tête
Content-Typede la requête est défini surapplication/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 HTTP de base est l'une des formes d'authentification les plus simples. Elle est utilisée par de nombreuses API.
L'authentification est effectuée en associant un nom d'utilisateur et un mot de passe encodés aux en-têtes HTTP de chaque requête.

Créer une requête
Pour produire une requête authentifiée, procédez comme suit :
- Formez la phrase secrète en joignant le nom d'utilisateur et le mot de passe avec un signe deux-points, par exemple
username:password. - Encodez la phrase secrète en base64. Par exemple,
username:passworddevientdXNlcm5hbWU6cGFzc3dvcmQ=. - Associez un en-tête
Authorizationà la requête, au formatAuthorization: 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 illustrant l'utilisation de l'authentification de base HTTP :
Plivo
Plivo est un service qui facilite l'envoi et la réception de SMS avec son API. Cet exemple illustre l'envoi de messages.
- Inscrivez-vous sur Plivo.
- Collez l'exemple de script dans un nouveau script dans Google Ads.
- Remplacez les valeurs
PLIVO_ACCOUNT_AUTHIDetPLIVO_ACCOUNT_AUTHTOKENpar les valeurs du tableau de bord de gestion. - Insérez votre adresse e-mail comme indiqué dans le script pour recevoir des notifications d'erreur.
- 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 s'affichera en tant qu'expéditeur et le numéro du destinataire.
- Remplacez
PLIVO_SRC_PHONE_NUMBERdans le script par l'un des numéros de bac à sable que vous venez d'enregistrer. Il doit inclure l'indicatif international du pays, par exemple447777123456pour un numéro britannique.
Twilio
Twilio est un autre service qui facilite l'envoi et la réception de SMS avec son API. Cet exemple illustre l'envoi de messages.
- Inscrivez-vous sur Twillio.
- Collez l'exemple de script dans un nouveau script dans Google Ads.
- Remplacez les valeurs
TWILIO_ACCOUNT_SIDetTWILIO_ACCOUNT_AUTHTOKENpar celles affichées sur la page de la console du compte. - Remplacez
TWILIO_SRC_PHONE_NUMBERpar le numéro du tableau de bord. Il s'agit du numéro autorisé par Twilio pour envoyer des messages.
OAuth 1.0
De nombreux services populaires utilisent OAuth pour l'authentification. OAuth est disponible dans plusieurs versions.
Alors qu'avec l'authentification HTTP de base, un utilisateur ne dispose que d'un seul nom d'utilisateur et d'un seul mot de passe, OAuth permet aux applications tierces d'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. S'authentifier avec OAuth. Dans le cas d'une autorisation OAuth 1.0 complète à trois acteurs, le processus est le suivant :
- 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 puissent utiliser OAuth 1.0 sans interaction de l'utilisateur (comme l'exigent 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 de passer directement à l'étape 4. C'est ce qu'on appelle le protocole OAuth 1.0 à une étape.

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 console ou la page des paramètres d'administration du service, il est généralement nécessaire d'effectuer les opérations suivantes :
- 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 étape.
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é autorise des applications spécifiques à accéder aux données utilisateur. Les avantages sont les suivants :
- Il n'a pas besoin de partager les identifiants de son compte avec l'application.
- Vous pouvez contrôler quelles applications ont accès aux données individuellement et dans quelle mesure. (Par exemple, l'accès accordé peut être en lecture seule ou limité à un sous-ensemble des 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, cela implique de configurer une application dans la console du service tiers. Cette application représente votre script.
Vous spécifiez les droits d'accès à accorder à l'application des scripts Google Ads, et un ID client lui est généralement attribué. Cela vous permet, via OAuth 2.0, de contrôler quelles applications 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
Autorisez l'accès au serveur distant. Selon le type d'autorisation autorisé par le serveur, un ensemble d'étapes différent, appelé flux, doit être suivi. Toutefois, toutes les étapes aboutissent à l'émission d'un jeton d'accès qui sera utilisé pour cette session pour toutes les requêtes ultérieures.
Envoyer 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 à des scénarios d'utilisation différents. Par exemple, un flux différent est utilisé lorsqu'un utilisateur participe à une session interactive, par opposition à un scénario dans lequel une application doit s'exécuter en arrière-plan sans qu'un utilisateur soit présent.
Les fournisseurs d'API décident des types d'autorisation qu'ils acceptent, ce qui détermine la manière dont l'utilisateur procède à l'intégration de leur API.
Implémentation
Pour tous les 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.
Un exemple de bibliothèque 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'[attribution des identifiants client][client-credentials-rfc] est l'une des formes les plus simples de flux OAuth2, dans laquelle l'application échange un ID et un secret, uniques à l'application, en échange de l'émission d'un jeton d'accès limité dans le temps.

// 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
Attribution de jeton d'actualisation
L'attribution de jeton d'actualisation est semblable à l'attribution d'identifiants client, dans la mesure où une requête adressée au serveur renvoie un jeton d'accès pouvant être utilisé dans la session.

Obtenir un jeton d'actualisation
La différence avec l'attribution de jeton d'actualisation est que, alors que les détails requis pour une 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][authorization-code-rfc], qui nécessite une interaction de l'utilisateur :

- Utiliser OAuth Playground pour obtenir un jeton d'actualisation
OAuth2 Playground fournit une UI qui permet à l'utilisateur de suivre les étapes 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 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 code secret : identifiants de l'application.

Utilisation des jetons d'actualisation
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 :
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 possibles, consultez la documentation de référence de l'API Search Ads 360.
Créer le script
- Créez un projet dans la console Google Cloud, 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 Search Ads 360. Veillez à activer l'API Search Ads 360.
- Collez l'[exemple de script][search-ads-360-example] dans un nouveau script dans Google Ads.
- Collez l'[exemple de bibliothèque OAuth2][oauth20-library-example] 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 Apps Script Execution
Cet exemple illustre l'exécution d'une fonction dans Apps Script à l'aide de l'API Apps Script Execution. Cela vous permet d'appeler Apps Script à partir de scripts Google Ads.
Créer un script Apps Script
Créer 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 Ressources > Projet Cloud Platform.
- Cliquez sur le nom du projet pour accéder à la console Google Cloud.
- Accédez à API et services.
- Activez les API appropriées, en l'occurrence l'API Drive et l'API Apps Script Execution.
- Créez des identifiants OAuth à partir de l'élément Identifiants du menu.
- Revenez à votre script et publiez-le pour l'exécuter en cliquant sur 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][oauth20-library-example] 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'autorisation.
Les comptes de service diffèrent des types d'autorisation, car 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 utilise l'API Drive pour créer un fichier, celui-ci appartient au compte de service et n'est pas accessible par défaut au propriétaire du projet.
Exemple d'API Google Natural Language
L'[API Natural Language][natural-language-api-docs] fournit une [analyse des sentiments][sentiment-analysis-api-docs] et une [analyse des entités][entity-analysis-api-docs] pour le texte.
Cet exemple illustre le calcul du [sentiment][sentiment-api-docs] pour le texte d'une annonce, y compris le titre ou la description. Cela permet de mesurer le caractère positif du message et son ampleur : qu'est-ce qui est préférable, Nous vendons des gâteaux ou Nous vendons les meilleurs gâteaux de Londres ? Achetez aujourd'hui !?
Configurer le script
- Créez un projet dans la console Google Cloud.
- Activez l'[API Natural Language][natural-language-api].
- Activez la facturation pour le projet.
- [Créer un compte de service][create-service-account]. Téléchargez le fichier JSON d'identifiants.
- Collez l'[exemple de script][natural-language-example] dans un nouveau script dans Google Ads.
- Collez également l'[exemple de bibliothèque OAuth2][oauth20-library-example] sous la liste de code.
- Remplacez les valeurs nécessaires :
serviceAccount: adresse e-mail du compte de service, par exemplexxxxx@yyyy.iam.gserviceaccount.com.key: clé du fichier JSON téléchargé lors de la création du compte de service. Commence à-----BEGIN PRIVATE KEY...et se termine à...END PRIVATE KEY-----\n.
Réponses de l'API
Les API peuvent renvoyer des données dans différents formats. Les plus notables sont XML et JSON.
JSON
Le format de réponse JSON est généralement plus simple à utiliser que le format XML. Cependant, certains problèmes peuvent encore survenir.
Validation des réponses
Une fois que vous avez obtenu une réponse positive de l'appel à 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 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
XmlService permet à vos scripts d'analyser et d'extraire des données des corps de réponse XML.
Validation
Le format XML est encore 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 parse de XmlService :
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 ne permet pas de valider le fichier XML par rapport à un schéma.
Élément racine
Une fois le document XML analysé, 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 pour les matchs sélectionnés. La réponse XML se présente au format suivant :
<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
<schedule>
...
</schedule>
</schedule_schedules>
Notez comment l'espace de noms est spécifié dans l'élément racine. Pour cette raison, il est nécessaire de :
- Extrayez l'attribut d'espace de noms du document.
- Utilisez cet espace de noms lorsque vous parcourez les éléments enfants et que vous y accédez.
L'exemple suivant montre comment accéder à l'élément <schedule> et rechercher ses éléments enfants <sport_event> dans l'extrait de document précédent :
const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);
Obtenir des valeurs
Compte tenu de l'exemple de calendrier de football :
<sport_event_status status="..." ... />
Les attributs peuvent être récupérés, par exemple :
const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();
Le texte contenu dans un élément peut être lu à l'aide de getText(), mais il sera concaténé s'il existe 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 d'informations sur des matchs de football, en particulier des 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.
- Inscrivez-vous pour obtenir un compte d'essai.
- Une fois l'inscription terminée, connectez-vous à votre compte.
- Une fois connecté, accédez à Mon compte.
Sportradar sépare les différents sports dans différentes API. 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 Create a new Application (Créer une application). Donnez un nom et une description à l'application, et ignorez le champ "Website" (Site Web).
- Sélectionnez uniquement Émettre une nouvelle clé pour Soccer Trial 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 nouvelle clé émise, puis modifiez le champ de l'adresse e-mail.
Dépannage
Lorsque vous travaillez avec des API tierces, des erreurs peuvent se produire pour plusieurs raisons, par exemple :
- Les clients envoient des requêtes au serveur dans un format non attendu par l'API.
- Les clients 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 comme espaces réservés.
- Clients atteignant les limites d'utilisation.
- Clients fournissant des paramètres non valides.
Dans tous ces cas, et dans d'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 renvoyant une erreur (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 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 OKindique que l'opération a réussi. 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 est plus appropriée et renvoie les données dont vous avez besoin.
- L'API a peut-être changé depuis l'écriture du code. Consultez la documentation ou contactez le développeur pour obtenir des éclaircissements.
400 Bad Requestsignifie généralement qu'un élément est incorrect dans la mise en forme ou la structure de la requête envoyée au serveur. Inspectez la requête et comparez-la aux spécifications de l'API pour vous assurer qu'elle est conforme aux attentes. Pour en savoir plus sur l'examen des requêtes, consultez Inspecter les requêtes.401 Unauthorizedsignifie 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
Authorizationest construit 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 que les identifiants nécessaires à la requête sont fournis.
- Si l'API utilise l'autorisation de base, assurez-vous que l'en-tête
403 Forbiddenindique que l'utilisateur n'est pas autorisé à accéder à la ressource demandée.- Assurez-vous que l'utilisateur dispose des autorisations nécessaires, par exemple en lui accordant l'accès à un fichier dans une requête basée sur un fichier.
404 Not Foundsignifie 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 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, 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(url,
params).
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 est correcte.
Par exemple, si les données de formulaire de votre requête sont constituées de nombreuses chaînes concaténées, l'erreur peut se trouver 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);
// ...
vous permet d'inspecter les éléments de la requête.
Enregistrer 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 en remplacement de UrlFetchApp.fetch() pour consigner les requêtes et les réponses.
Remplacez toutes les instances de
UrlFetchApp.fetch()dans votre code parlogUrlFetch().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 consignés dans la console, ce qui facilite le débogage.
[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities