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

API tierces

Les scripts Google Ads peuvent s'intégrer aux données, et services 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 les utiliser UrlFetchApp pour y accéder aux API externes.
Authentification: nous abordons quelques scénarios d'authentification courants.
Analyse des réponses: comment traiter les données JSON et XML renvoyées.

Nous incluons également exemples pour obtenir un nombre d'API populaires illustrant ces concepts.

Récupérer des données avec UrlFetchApp

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

L'exemple suivant illustre la récupération de données météorologiques à partir de OpenWeatherMap : Nous avons choisi OpenWeatherMap pour son schéma d'autorisation et son API relativement simples.

Envoyer une requête

La documentation OpenWeatherMap spécifie format 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 sa valeur est propre à chaque utilisateur. Cette clé est obtenue via inscription.

Après l'inscription, une demande utilisant la clé peut être envoyée 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 code JSON texte écrit dans la fenêtre de journalisation des scripts Google Ads.

L'étape suivante consiste à le convertir dans un format utilisable dans votre script.

Données JSON

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

Pour convertir une chaîne JSON, comme celle renvoyée par OpenWeatherMap : dans un objet JavaScript, utilisez l'API JSON.parse. 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

Consultez la section Analyser les réponses pour en savoir plus sur avec des réponses de l'API dans différents formats.

Traiter les erreurs

La gestion des erreurs est un aspect important à prendre en compte lorsque vous utilisez des API tierces dans vos scripts, car les API tierces 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 du risque de réponses inattendues, nous vous recommandons d'inspecter la page HTTP code d'état. Par défaut, UrlFetchApp génère une exception si un code d'erreur HTTP est détecté. À ce comportement, il est nécessaire de 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 les API tierces changent, les développeurs n'ont souvent pas immédiatement connaissance modifications qui pourraient affecter leurs scripts. Par exemple, si la propriété name renvoyé dans l'exemple OpenWeatherMap est remplacé par locationName, les scripts l'utilisation de cette propriété échouera.

C'est pourquoi il peut être utile de tester si la structure renvoyée est comme prévu, 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 que les données récupérées. En règle générale, les appels d'API qui ne changent pas d'état au niveau utilisez la méthode HTTP GET .

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

Pour illustrer l'utilisation des appels POST avec UrlFetchApp, l'exemple suivant Montre l'intégration à Slack, un service de messagerie collaborative pour envoyer un message Slack à des utilisateurs et à des groupes Slack.

Configurer Slack

Dans ce guide, nous partons du principe que vous êtes déjà inscrit à un compte Slack.

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

Configurer un webhook entrant en cliquant sur Ajoutez l'intégration de webhooks entrants et suivez les instructions. La doit émettre une URL à utiliser pour la messagerie.

Envoyer une requête POST

Après avoir configuré votre webhook entrant, l'envoi d'une requête POST requiert simplement l'utilisation de propriétés supplémentaires dans le paramètre options transmis à UrlFetchApp.fetch:

method: comme indiqué précédemment, la valeur par défaut est GET, mais ici, nous la remplaçons et définissez-la sur POST.

payload: données à envoyer au serveur dans le cadre de POST. requête. Dans cet exemple, Slack attend un objet sérialisé au format JSON. comme décrit dans la documentation Slack documentation. Pour cela, le champ 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 d'extension Slack

L'exemple ci-dessus montre le minimum requis pour activer les messages entrants dans Slack. Une sample étendu la création et l'envoi d'un rapport Performances des campagnes Signalez à un ainsi que des options de mise en forme et d'affichage.

Message entrant

Consultez la section Mise en forme des messages dans le Slack pour en savoir plus sur les messages Slack.

Données de formulaire

L'exemple ci-dessus illustre l'utilisation d'une chaîne JSON en tant que propriété payload. pour la requête POST.

En fonction du format de payload, UrlFetchApp adopte différentes approches à la construction de la requête POST:

Lorsque payload est une chaîne, l'argument de chaîne est envoyé en tant que le 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 de formulaire:
```
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. Par conséquent, conversion automatique des objets JavaScript en données de formulaire. à l'esprit.

Authentification HTTP de base

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

L'authentification s'effectue en joignant un nom d'utilisateur et un mot de passe codés au En-têtes HTTP dans chaque requête.

Authentification HTTP de base

Créer une requête

Procédez comme suit pour produire une requête authentifiée:

Pour créer la phrase secrète, associez le nom d'utilisateur et le mot de passe à l'aide d'un 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);

Exemples d'authentification de base

Les 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 de réception de SMS via son API. Cet exemple illustre l'envoi 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 les du tableau de bord de gestion.
Insérez votre adresse e-mail comme indiqué dans le script de notification de les erreurs.
Pour utiliser Plivo, vous devez acheter des numéros ou ajouter des numéros à l'essai Google Cloud. Ajoutez des numéros de bac à sable qui peuvent être utilisée avec le compte d'essai.
Ajoutez à la fois le numéro qui apparaîtra comme expéditeur et comme destinataire numéro.
Dans le script, remplacez PLIVO_SRC_PHONE_NUMBER par l'un des numéros de bac à sable. qui vient d'être enregistré. Il doit inclure l'indicatif international du pays, par exemple Exemple : 447777123456 pour un numéro britannique

Twilio

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

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

OAuth 1.0

De nombreux services populaires utilisent OAuth pour l'authentification. OAuth est disponible types et versions.

Avec l'authentification HTTP de base, n'a qu'un nom d'utilisateur et un mot de passe, OAuth permet aux applications tierces qui peut accéder au compte et aux données d'un utilisateur à l'aide d'identifiants spécifiques une application tierce. De plus, l'étendue de l'accès sera également spécifiques à cette application.

Pour en savoir plus sur OAuth 1.0, consultez le guide OAuth Core. Consultez en particulier la section 6. S'authentifier avec OAuth En plein à trois jambes OAuth 1.0, 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 demandes de ressources ultérieures, le jeton d'accès est utilisé dans un contrat de niveau de service requête.

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

OAuth1

OAuth 1.0 dans les scripts Google Ads

Dans le cas des scripts Google Ads, chaque script est généralement interprété comme une application. Sur la page des paramètres d'administration/de la console du service, il s'agit généralement nécessaires pour:

Définissez une configuration d'application pour représenter le script.
Spécifiez les autorisations qui seront étendues au script.
Obtenir la clé client, le code secret client, le jeton d'accès et le code secret d'accès à utiliser avec OAuth en mode une personne.

OAuth 2.0

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

N'a pas besoin de partager les identifiants de son compte avec l'application.
peuvent contrôler quelles applications ont accès aux données individuellement, ainsi que dans quelle mesure. Par exemple, l'accès accordé peut être en lecture seule ou seulement pour sous-ensemble de données.)

Pour utiliser les services compatibles OAuth 2.0 dans les scripts Google Ads, il existe plusieurs étapes:

En dehors de votre script

Autorisez les scripts Google Ads à accéder à vos données utilisateur via le une API tierce. Dans la plupart des cas, cela implique de mettre en place 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 Google Ads Script doit avoir. donné, et il se voit généralement attribuer un ID client. Cela vous permet, à travers OAuth 2 pour contrôler les applications qui ont accès à vos données dans un service tiers, ainsi que les aspects de ces données qu'il peut consulter ou modifier.

Dans votre script

Autoriser avec le serveur distant Selon le type d'octroi, autorisé par le serveur, un ensemble d'étapes différent, appelé flux, devra mais tous donneront lieu à un jeton d'accès qui sera utilisée pour cette session pour toutes les demandes ultérieures.

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

Flux d'autorisations

Chaque type d'attribution et chaque flux correspondant s'adaptent à différents scénarios d'utilisation. Pour Par exemple, un flux différent est utilisé lorsqu'un utilisateur participe à un événement une session, contrairement à ce qui se produit lorsqu'une application doit s'exécuter dans en arrière-plan sans la présence d'un utilisateur.

Les fournisseurs d'API choisiront les types d'octroi qu'ils accepteront, ce qui les guidera comment l'utilisateur procède à l'intégration de son API.

Implémentation

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

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

Le modèle d'utilisation générale 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'octroi d'identifiants client est l'une des formes les plus simples de flux OAuth2, dans laquelle l'application échange identifiant et code secret, propres à l'application, en échange de l'émission d'une jeton d'accès à durée limitée.

Identifiants du 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

Accorder l'autorisation du jeton d'actualisation

L'attribution du jeton d'actualisation est semblable à celle des identifiants client, dans la mesure où Une simple requête envoyée au serveur renvoie un jeton d'accès que vous pouvez utiliser pendant la session.

Jeton d'actualisation

Obtenir un jeton d'actualisation

La différence avec l'octroi d'un jeton d'actualisation est que, tandis que les détails requises pour l'attribution des identifiants client proviennent de la configuration (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 code d'autorisation d'autorisation, ce qui obligera interaction:

Code d'autorisation

Utiliser OAuth Playground pour obtenir un jeton d'actualisation

OAuth2 Playground fournit une interface utilisateur qui permet à l'utilisateur de suivre le 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 de l'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 secret: identifiants de l'application.

OAuth Playground

Utiliser un script pour obtenir un jeton d'actualisation

Une alternative basée sur un script à la fin du flux est disponible dans la jeton d'actualisation génération échantillon.

Actualiser l'utilisation des jetons

Une fois l'autorisation initiale effectuée, les services peuvent actualiser la page. 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 une rapport. Consultez le Réseau de Recherche Documentation de référence de l'API 360 pour en savoir plus sur les autres actions que vous pouvez effectuer.

Créer le script

Créez un projet dans la console API. et d'obtenir un ID client, un code secret du client et un jeton d'actualisation en suivant le dans le guide DoubleClick, en vous assurant d'activer l'API DoubleClick Search.
Collez l'exemple de script dans un nouveau script dans Google Ads.
Collez l'exemple OAuth2. bibliothèque sous .
Modifiez le script pour qu'il contienne les valeurs correctes pour le numéro client, le code secret du client, et le jeton d'actualisation.

Exemple avec l'API Apps Script Execution

Cet exemple illustre l'exécution d'une fonction dans Apps Script à l'aide de la classe Apps API Script Execution. Cela permet à Apps Script être appelé à partir de scripts Google Ads.

Créer un script Apps Script

Créez un script. L'exemple suivant répertorie 10 fichiers stockés dans 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 APIs.
Accédez à API et Services.
Activez les API appropriées. Dans ce cas, le service Drive Google Cloud, et les applications Exécution du script API.
Créez des identifiants OAuth depuis l'élément Credentials (Identifiants) du menu.
Retournez dans votre script, puis publiez le script 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 dans le script un nouveau script dans Google Ads.
De plus, collez l'exemple OAuth2 bibliothèque sous .
Modifiez le script pour qu'il contienne les valeurs correctes pour le numéro client, le code secret du client, et le jeton d'actualisation.

Comptes de service

Une alternative aux types de subventions mentionnés ci-dessus est le concept de service comptes Google.

Les comptes de service diffèrent des comptes ci-dessus dans le sens où ils ne sont pas utilisés pour accéder données: 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 devaient utiliser l'API Drive pour créer un fichier, au compte de service et, par défaut, ne sont pas accessibles propriétaire du projet.

Exemple d'utilisation de l'API Google Natural Language

L'API Natural Language fournit Sentiment l'analyse et entité l'analyse pour le texte.

Cet exemple illustre le calcul de la valeur ressentiment pour le texte d'annonce, y compris le titre ou la description. Cela permet de mesurer le degré de positivité et d'ampleur du message. Laquelle est la meilleure, 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'option Natural Language API
Activez la facturation pour le projet.
Créer un service Compte. Téléchargez le fichier JSON des identifiants.
Collez l'exemple du script dans une nouvelle dans Google Ads.
De plus, collez l'exemple OAuth2 bibliothèque sous .
Remplacez les valeurs nécessaires: <ph type="x-smartling-placeholder">
- 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 service Compte. Offre valable du -----BEGIN PRIVATE KEY... au ...END PRIVATE KEY-----\n.

Réponses d'API

Les API peuvent renvoyer des données dans différents formats. Les plus importants d'entre eux sont le format XML, et JSON.

JSON

Il est généralement plus simple d'utiliser JSON que XML sous forme de fichier le format de réponse. Toutefois, certains problèmes peuvent encore survenir.

Validation de réponse

Après avoir obtenu une réponse positive de l'appel à l'API, la méthode type L'étape suivante consiste à utiliser JSON.parse pour convertir la chaîne JSON en un fichier JavaScript . À ce stade, il est judicieux de gérer le cas où l'analyse fails:

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

Par ailleurs, si vous ne gérez pas l'API, n'oubliez pas que la structure peut changer et les propriétés risquent de 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

XML est toujours un format populaire pour créer des API. Réponse d'un appel d'API peuvent être analysées à l'aide XmlService parse méthode:

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

Alors que XmlService.parse détecte des erreurs dans le fichier XML et génère des exceptions Par conséquent, il ne permet pas de valider le code XML par rapport à du schéma.

Élément racine

L'élément racine est obtenu en raison de l'analyse réussie du document XML. à 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é pour obtenir les résultats des matchs sélectionnés. La réponse XML prend au format suivant:

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

Notez comment l'espace de noms est spécifié dans l'élément racine. Pour cette raison, nécessaires pour:

Extrayez l'attribut d'espace de noms du document.
Utilisez cet espace de noms lors du balayage des éléments enfants et de l'accès à ceux-ci.

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

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

Dans l'échantillon du calendrier football:

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

Les attributs peuvent être récupérés, par exemple:

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

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

Exemple de Sportradar

Ce Sportradar complet exemple illustre des informations sur des matchs de football, en particulier la Premier League anglaise, correspond. 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 différents sports dans différentes API. Par exemple : peut acheter l'accès à l'API Soccer, mais pas à l'API Tennis. Chaque L'application que vous créez peut être associée à différents sports. différentes clés.

Sous "Applications", cliquez sur Create a new Application (Créer une application). Attribuer à l'application un nom et une description, et ignorer le champ du site web.
Sélectionnez uniquement l'option É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 Google Ads.
Remplacez la clé API indiquée dans la fiche par celle obtenue ci-dessus, puis modifiez la adresse e-mail.

Dépannage

Lorsque vous utilisez des API tierces, des erreurs peuvent se produire pour plusieurs raisons : Exemple:

Clients envoyant des requêtes au serveur dans un format non attendu par l'API.
Les clients s'attendent à un format de réponse différent de celui rencontré.
Clients utilisant des jetons, des clés ou des valeurs 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 dans d'autres, une bonne première étape pour identifier la cause d'examiner le détail de la réponse à l'origine de l'erreur.

Analyser les réponses

Par défaut, toute réponse renvoyant une erreur (un état code égal ou supérieur à 400) générées par le moteur de scripts Google Ads.

Pour éviter ce comportement, et pour permettre l'affichage de l'erreur et du message d'erreur avez inspecté, 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 la réussite de l'opération. Si la réponse ne contient pas les informations 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 le documentation pour déterminer si une autre ressource approprié à l’utilisation et renverra les données dont vous avez besoin.
- L'API a peut-être changé depuis que le code a été écrit. Consultez le ou au développeur pour plus de précisions.
400 Bad Request signifie généralement qu'un élément n'est pas correct dans le format ou structure de la requête envoyée au serveur. Inspectez et le comparer aux spécifications de l'API pour vérifier qu'il est conforme à vos attentes. Consultez la section Inspecter les requêtes pour en savoir plus sur comment examiner les demandes.
401 Unauthorized signifie généralement que l'API est appelée sans fournir ni de l'autorisation.
- Si l'API utilise une autorisation de base, assurez-vous que l'en-tête Authorization est construite et fournie dans la requête.
- Si l'API utilise OAuth 2.0, assurez-vous que le jeton d'accès a bien été obtenu et est fourni en tant que jeton de support.
- Pour toute autre variante d'autorisation, assurez-vous que les autorisations les identifiants de la requête sont fournis.
403 Forbidden indique que l'utilisateur ne dispose pas de l'autorisation pour la ressource demandé.
- Assurez-vous que l'utilisateur dispose des autorisations nécessaires, par exemple : donner à l’utilisateur l’accès à un fichier dans une requête basée sur un fichier.
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 requêtes

L'inspection des requêtes est utile lorsque les réponses de l'API indiquent que la requête est incorrecte composé, par exemple, d'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 inspecter les éléments de la requête pour vous assurer qu'elle est correcte.

Par exemple, si les données de formulaire contenues dans votre requête sont constitué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 ce formulaire données. Dans sa forme la plus 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.

Consigner les requêtes et les réponses

Pour vous aider tout au long du processus d'inspection des requêtes et des réponses à une une API tierce, vous pouvez utiliser la fonction d'assistance suivante 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 consignés dans la console, ce qui facilite le débogage.