Drittanbieter-APIs

Eine leistungsstarke Funktion von Google Ads-Skripts ist die Möglichkeit, und Dienste von Drittanbieter-APIs.

In diesem Handbuch werden die folgenden Konzepte behandelt, die Ihnen beim Schreiben von Skripts für eine Verbindung zu anderen Diensten herstellen:

  • HTTP-Anfragen stellen: Anleitung Zum Zugriff über UrlFetchApp und externen APIs.
  • Authentifizierung: Wir behandeln einige gängige Authentifizierungsszenarien.
  • Antworten parsen: So werden zurückgegebene JSON- und XML-Daten verarbeitet.

Wir berücksichtigen auch Beispiele für eine Zahl gängiger APIs, die diese Konzepte veranschaulichen.

Daten mit UrlFetchApp abrufen

UrlFetchApp stellt die Hauptfunktionen, die für die Interaktion mit APIs von Drittanbietern erforderlich sind.

Im folgenden Beispiel sehen Sie, wie Wetterdaten aus OpenWeatherMap Wir haben uns für OpenWeatherMap entschieden, das relativ einfache Autorisierungsschema und die API.

Anfrage stellen

In der OpenWeatherMap-Dokumentation wird angegeben, Format zum Anfordern des aktuellen Wetters wie folgt:

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

Die URL zeigt unser erstes Beispiel für eine Autorisierung: Der Parameter apikey lautet erforderlich und der Wert ist für jeden Nutzer eindeutig. Dieser Schlüssel wird über zum Registrieren.

Nach der Registrierung kann eine Anfrage mit dem Schlüssel folgendermaßen gesendet werden:

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

Bei der Ausführung dieses Codes wird ein langer String von JSON zurückgegeben. Text, der in das Protokollierungsfenster in Google Ads-Skripts geschrieben wird.

Im nächsten Schritt müssen Sie es in ein Format konvertieren, das in Ihrem .

JSON-Daten

Viele APIs stellen Antworten im JSON-Format bereit. Dies stellt eine einfache Serialisierung von JavaScript-Objekten, sodass Objekte, Arrays und Basistypen als Strings dargestellt und übertragen werden können.

Um einen JSON-String zu konvertieren, wie den von OpenWeatherMap: Kehren Sie mithilfe der integrierten JSON.parse-Methode. Fortsetzung des obigen Beispiels:

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

Die Methode JSON.parse konvertiert den String in ein Objekt, das ein Attribut hat. name.

Weitere Informationen finden Sie im Abschnitt Antworten parsen. mit API-Antworten in verschiedenen Formaten arbeiten.

Fehlerbehandlung

Die Fehlerbehandlung ist ein wichtiger Aspekt bei der Arbeit mit APIs von Drittanbietern in Ihren Skripts, da Drittanbieter-APIs häufig geändert werden und Unerwartete Antwortwerte, zum Beispiel:

  • Die URL oder die Parameter für die API können ohne Ihr Wissen geändert werden.
  • Ihr API-Schlüssel (oder andere Nutzeranmeldedaten) läuft ab.
  • Das Format der Antwort kann ohne vorherige Ankündigung geändert werden.

HTTP-Statuscodes

Aufgrund der Möglichkeit unerwarteter Antworten sollten Sie den HTTP Statuscode. Standardmäßig UrlFetchApp löst eine Ausnahme aus, wenn ein HTTP-Fehlercode auftritt. Bis dieses Verhalten ändern, ist es notwendig, einen optionalen Parameter zu übergeben, wie in der folgendes Beispiel:

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

Antwortstruktur

Wenn sich Drittanbieter-APIs ändern, wissen Entwickler oft nicht sofort, die sich auf ihre Skripts auswirken. Wenn beispielsweise das Attribut name im OpenWeatherMap-Beispiel in locationName geändert wird, schlägt fehl.

Aus diesem Grund kann es hilfreich sein zu testen, ob die zurückgegebene Struktur wie erwartet, zum Beispiel:

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

POST-Daten mit UrlFetchApp

Das einführende Beispiel mit OpenWeatherMap abgerufene Daten. In der Regel werden API-Aufrufe, die den Status auf dem Remote-Server nicht ändern, Server verwenden den HTTP GET .

Die Methode GET ist die Standardmethode für UrlFetchApp. Einige API-Aufrufe etwa für Anrufe bei einem Dienst, der SMS sendet, andere Methoden, wie POST oder PUT.

Das folgende Beispiel veranschaulicht die Verwendung von POST-Aufrufen mit UrlFetchApp. Demonstriert die Integration mit Slack, einem Messaging-Tool für die Zusammenarbeit -Anwendung, um eine Slack-Nachricht an Slack-Nutzer und -Gruppen zu senden.

Slack einrichten

In diesem Leitfaden wird davon ausgegangen, dass Sie sich bereits für ein Slack-Konto registriert haben.

Wie bei OpenWeatherMap im vorherigen Beispiel ist es erforderlich, um das Senden von Nachrichten zu ermöglichen. Slack stellt eine eindeutige URL bereit, mit der Sie Nachrichten an Ihr Team senden. Dieser wird als Eingehender Webhook bezeichnet.

Richten Sie einen eingehenden Webhook ein, indem Sie auf Fügen Sie eine eingehende Webhooks-Integration hinzu und folgen Sie der Anleitung. Die eine URL für Nachrichten ausgeben sollte.

POST-Anfrage stellen

Nach der Einrichtung des eingehenden Webhooks POST müssen Sie die Verwendung einiger zusätzlicher Eigenschaften im options-Parameter, der an UrlFetchApp.fetch:

  • method: Wie bereits erwähnt, ist die Standardeinstellung GET, aber hier überschreiben wir ihn und legen Sie POST fest.

  • payload: Dies sind die Daten, die im Rahmen des POST an den Server gesendet werden. In diesem Beispiel erwartet Slack ein Objekt, das im JSON-Format serialisiert ist. wie in der Slack-Dokumentation Dokumentation. In diesem Fall JSON.stringify wird verwendet und Content-Type ist auf application/json gesetzt.

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

Beispiel für erweitertes Slack

Das obige Beispiel zeigt das Minimum, um eingehende Nachrichten in Slack zu aktivieren. Eine Erweitertes Beispiel veranschaulicht die Erstellen und Senden einer Kampagnenleistung Melden an eine sowie einige Formatierungs- und Anzeigeoptionen.

Eingehende Nachricht

Siehe Nachrichtenformatierung in Slack .

Formulardaten

Im obigen Beispiel wird die Verwendung eines JSON-Strings als payload-Attribut veranschaulicht. für die POST-Anfrage.

Je nach Format von payload verfolgt UrlFetchApp unterschiedliche Ansätze um die POST-Anfrage zu erstellen:

  • Wenn payload ein String ist, wird das Stringargument als Text der Anfrage.

  • Wenn payload ein Objekt ist, z. B. eine Zuordnung von Werten:

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}

    Die Schlüssel/Wert-Paare werden in Formulardaten konvertiert:

    subject=Test&to=mail@example.com&body=Hello,+World!

    Außerdem ist der Content-Type-Header für die Anfrage auf application/x-www-form-urlencoded.

Einige APIs erfordern die Verwendung von Formulardaten beim Senden von POST-Anfragen, sodass dies automatische Konvertierung von JavaScript-Objekten in Formulardaten ist nützlich, im Hinterkopf behalten.

HTTP-Basisauthentifizierung

HTTP Basic Authentifizierung ist eine von die einfachste Form der Authentifizierung und wird von vielen APIs verwendet.

Die Authentifizierung erfolgt durch Anhängen eines codierten Nutzernamens und Passworts an die HTTP-Header in jeder Anfrage.

HTTP-Basisauthentifizierung

Anfrage erstellen

Die folgenden Schritte sind erforderlich, um eine authentifizierte Anfrage zu erstellen:

  1. Erstellen Sie die Passphrase, indem Sie Nutzername und Passwort mit einem Doppelpunkt, z. B. username:password.
  2. Base64-Codierung der Passphrase. Beispiel: username:password wird zu dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Hängen Sie einen Authorization-Header im Format Authorization: Basic <encoded passphrase> an die Anfrage an.

Das folgende Snippet veranschaulicht, wie dies in Google Ads-Skripts umgesetzt wird:

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

Beispiele für die Basisauthentifizierung

Codebeispiele enthält zwei Beispiele, die die Verwendung der HTTP-Basisauthentifizierung veranschaulichen:

Plivo

Plivo ist ein Dienst, der das Senden und Empfang von SMS-Nachrichten über ihre API. Dieses Beispiel veranschaulicht, Nachrichten.

  1. Registrieren Sie sich bei Plivo.
  2. Fügen Sie das Beispielskript ein neues Skript in Google Ads erstellen.
  3. Ersetzen Sie die Werte PLIVO_ACCOUNT_AUTHID und PLIVO_ACCOUNT_AUTHTOKEN durch die aus dem Verwaltungsdashboard.
  4. Geben Sie Ihre E-Mail-Adresse wie im Skript für die Benachrichtigung über Fehler.
  5. Wenn Sie Plivo verwenden möchten, müssen Sie entweder Nummern kaufen oder der Testversion Nummern hinzufügen Konto. Sandbox-Nummern hinzufügen, die kann mit dem Testkonto verwendet werden.
  6. Fügen Sie die Nummer, die als Absender angezeigt wird, und den Empfänger hinzu Nummer.
  7. Aktualisieren Sie PLIVO_SRC_PHONE_NUMBER im Skript auf eine der Sandbox-Nummern gerade registriert. Hier muss der internationale Ländercode für Beispiel: 447777123456 für eine Nummer aus dem Vereinigten Königreich.

Twilio

Twilio ist ein weiterer Dienst, der das Senden und SMS-Nachrichten über ihre API empfangen können. Dieses Beispiel veranschaulicht, Nachrichten.

  1. Registrieren Sie sich bei Twillio.
  2. Fügen Sie das Beispielskript ein. in ein neues Skript in Google Ads.
  3. Ersetzen Sie die Werte TWILIO_ACCOUNT_SID und TWILIO_ACCOUNT_AUTHTOKEN durch die werden auf der Kontokonsolenseite angezeigt.
  4. Ersetzen Sie TWILIO_SRC_PHONE_NUMBER durch die Zahl aus der Dashboard: Dies ist die Nummer, die von Twilio zum Senden von Nachrichten autorisiert wurde.

OAuth 1.0

Viele beliebte Dienste verwenden OAuth zur Authentifizierung. OAuth gibt es in verschiedenen Geschmacksrichtungen und Versionen.

Bei der HTTP-Basisauthentifizierung hingegen nur einen Nutzernamen und ein Passwort hat, können Drittanbieteranwendungen mit OAuth dem Zugriff auf das Konto und die Daten eines Nutzers gewährt wurde. Dazu werden spezielle Anmeldedaten verwendet. einer Drittanbieter-App. Außerdem wird auch der Umfang des Zugriffs speziell für diese Anwendung.

Hintergrundinformationen zu OAuth 1.0 finden Sie im OAuth Core-Leitfaden. Lesen Sie insbesondere den Abschnitt 6. Authentifizierung mit OAuth In voller dreibeiniger OAuth 1.0 ist der Ablauf so:

  1. Die Anwendung ("Consumer") erhält ein Anfrage-Token.
  2. Der Nutzer autorisiert das Anfragetoken.
  3. Die Anwendung tauscht das Anfrage-Token gegen ein Zugriffstoken aus.
  4. Für alle nachfolgenden Ressourcenanfragen wird das Zugriffstoken in einem signierten

Damit Drittanbieterdienste OAuth 1.0 ohne Nutzerinteraktion verwenden (z. B. da dies für Google Ads-Skripts erforderlich wäre) die Schritte 1, 2 und 3 sind nicht möglich. Daher geben einige Dienste ein Zugriffstoken aus ihrer Konfiguration aus sodass die Anwendung direkt mit Schritt 4 fortfahren kann. Dies wird als einbeiniges OAuth 1.0.

OAuth1

OAuth 1.0 in Google Ads-Skripts

Bei Google Ads-Skripts wird jedes Skript normalerweise als Anwendung interpretiert. Über die Seite mit den Konsolen-/Verwaltungseinstellungen für den Dienst erforderlich für:

  • Anwendungskonfiguration einrichten, die das Skript darstellt.
  • Geben Sie an, welche Berechtigungen auf das Skript erweitert werden sollen.
  • Consumer-Key, Consumer-Secret, Zugriffstoken und Zugriffs-Secret zur Verwendung abrufen mit einbeinigem OAuth.

oauth 2.0

OAuth 2.0 wird in gängigen APIs verwendet, um Zugriff auf Nutzerdaten. Der Inhaber eines Kontos für eine bestimmte Erteilung von Drittanbieterdiensten Berechtigung für bestimmte Anwendungen, um ihnen den Zugriff auf Nutzerdaten zu ermöglichen. Die Vorteile hat:

  • Er muss seine Kontoanmeldedaten nicht an die Anwendung weitergeben.
  • Sie können steuern, welche Anwendungen individuell auf die Daten zugreifen und in welchem Umfang. (Beispiel: Der gewährte Zugriff kann schreibgeschützt sein oder nur für einen bestimmten Teilmenge der Daten.)

Es gibt mehrere Möglichkeiten, OAuth 2.0-fähige Dienste in Google Ads-Skripts zu verwenden. Schritte:

Außerhalb des Skripts

Google Ads-Skripts den Zugriff auf Ihre Nutzerdaten über das Drittanbieter-API. In den meisten Fällen muss dazu eine application in der Konsole des Drittanbieterdienstes. Diese Anwendung steht für Ihr Google Ads-Skript.

Sie legen fest, welche Zugriffsrechte die Anwendung für das Google Ads Script-Skript erhalten soll. und normalerweise wird ihm eine Client-ID zugewiesen. So können Sie durch OAuth 2, mit dem Sie steuern können, welche Anwendungen auf Ihre Daten im und welche Aspekte dieser Daten ändern können.

Im Skript

Mit dem Remoteserver autorisieren Je nach Berechtigungstyp erlaubt, müssen andere Schritte, sogenannter Ablauf, ausgeführt werden, befolgt werden, doch alle führen letztendlich dazu, dass ein Zugriffstoken das für diese Sitzung für alle nachfolgenden Anfragen verwendet wird.

API-Anfragen stellen Übergeben Sie bei jeder Anfrage das Zugriffstoken.

Autorisierungsverfahren

Jeder Erteilungstyp und der entsprechende Ablauf sind auf unterschiedliche Nutzungsszenarien abgestimmt. Für Ein anderer Ablauf wird beispielsweise verwendet, wenn Nutzende an einem interaktiven im Gegensatz zu einem Szenario, in dem eine Anwendung ausgeführt werden muss, ohne Anwesenheit der Nutzenden.

API-Anbieter entscheiden, welche Arten von Förderlizenzen sie akzeptieren. wie der Nutzer mit der API-Integration fortfährt.

Implementierung

Ziel ist es, für die verschiedenen OAuth-Abläufe ein Zugriffstoken zu erhalten, können dann für den Rest der Sitzung zur Authentifizierung von Anfragen verwendet werden.

Beispielbibliothek zeigt, wie die Authentifizierung für jeden verschiedenen Ablauftyp funktioniert. Jede dieser Optionen -Methoden geben ein Objekt zurück, das das Zugriffstoken abruft und speichert. authentifizierte Anfragen erleichtern.

Das allgemeine Verwendungsmuster sieht so aus:

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

Gewährung von Clientanmeldedaten

Die geteilte Clientanmeldedaten lautet eine der einfacheren Formen des OAuth2-Ablaufs, bei dem die Anwendung ein ID und Secret, die für die Anwendung eindeutig sind, im Gegenzug für die Ausgabe eines zeitlich begrenzten Zugriffstoken.

Client-Anmeldedaten

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

Gewährung von Aktualisierungstoken

Die Gewährung von Aktualisierungstokens ähnelt der Gewährung von Clientanmeldedaten, Bei einer einfachen Anfrage an den Server wird ein Zugriffstoken zurückgegeben, das dann verwendet werden kann: in der Sitzung.

Aktualisierungstoken

Aktualisierungstoken abrufen

Der Unterschied zur Erteilung des Aktualisierungstokens besteht darin, dass die Details die für die Gewährung von Clientanmeldedaten erforderlich sind, stammen aus der Anwendungskonfiguration (z. B. im Steuerfeld des Dienstes), wird das Aktualisierungstoken als Teil eines komplexeren Ablaufs, wie z. B. als Autorisierungscode Grant, wofür ein Nutzer erforderlich ist, Interaktion:

Autorisierungscode

Aktualisierungstoken über OAuth Playground abrufen

Der OAuth2 Playground bietet eine UI, mit der Nutzer durch die Erteilung des Autorisierungscodes durchgehen, um ein Aktualisierungstoken abzurufen.

Mit der Schaltfläche „Einstellungen“ oben rechts können Sie alle Parameter zur Verwendung im OAuth-Ablauf:

  • Autorisierungsendpunkt: Wird als Beginn des Vorgangs für die Autorisierung verwendet.
  • Tokenendpunkt: Wird mit dem Aktualisierungstoken verwendet, um ein Zugriffstoken abzurufen.
  • Client-ID und Secret: Anmeldedaten für die Anwendung.

OAuth-Playground

Aktualisierungstoken mit einem Skript abrufen

Eine skriptbasierte Alternative zum Abschließen des Ablaufs finden Sie in der Aktualisierungstoken Generation Stichprobe.

Nutzung von Aktualisierungstokens

Sobald die erstmalige Autorisierung durchgeführt wurde, können Dienste eine Aktualisierung ausgeben Token, das dann auf ähnliche Weise wie der Ablauf der Clientanmeldedaten verwendet werden kann. Im Folgenden finden Sie zwei Beispiele:

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

Search Ads 360-Beispiel

Search Ads 360 ist ein Beispiel für eine API, die mit einem Aktualisierungstoken verwendet werden kann. In diesem Beispiel generiert ein Skript einen Bericht. Informieren Sie sich im Leitfaden für Suchanzeigen 360 API-Referenz mit ausführlichen Informationen zu anderen Aktionen die durchgeführt werden können.

Skript erstellen
  1. Erstellen Sie ein neues Projekt in der API Console. und rufen Sie eine Client-ID, einen Clientschlüssel und ein Aktualisierungstoken ab. Folgen Sie dazu der im DoubleClick-Leitfaden, und stellen Sie dabei sicher, dass Sie die DoubleClick Search API aktivieren.
  2. Beispiel einfügen Skript in ein Skript in Google Ads erstellen.
  3. Fügen Sie das Beispiel-OAuth2 ein. Bibliothek unterhalb des Code-Eintrag.
  4. Ergänzen Sie das Skript so, dass es die richtigen Werte für Client-ID, Clientschlüssel und Aktualisierungstoken.

Beispiel für die Apps Script Execution API

Dieses Beispiel zeigt, wie eine Funktion in Apps Script mithilfe der Funktion Apps Script Execution API hinzu. Dadurch können Apps Script können aus Google Ads-Skripts aufgerufen werden.

Apps Script-Script erstellen

Erstellen Sie ein neues Skript. Im folgenden Beispiel sehen Sie 10 Dateien aus Google Drive:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
Apps Script für die Ausführung konfigurieren
  1. Speichern Sie das Skript.
  2. Klicken Sie auf Ressourcen > Cloud Platform-Projekt.
  3. Klicken Sie auf den Projektnamen, um die API Console aufzurufen.
  4. Rufen Sie APIs und Dienste.
  5. Aktivieren Sie die entsprechenden APIs, in diesem Fall das Drive API und die Apps Skriptausführung API
  6. Erstellen Sie OAuth-Anmeldedaten aus dem Menüpunkt Anmeldedaten.
  7. Veröffentlichen Sie das Skript im Skript über Veröffentlichen > Als ausführbare API bereitstellen.
Google Ads-Skript erstellen
  1. Beispiel einfügen Script in ein neues Skript in Google Ads erstellen.
  2. Fügen Sie außerdem das OAuth2-Beispiel Bibliothek unterhalb des Code-Eintrag.
  3. Ergänzen Sie das Skript so, dass es die richtigen Werte für Client-ID, Clientschlüssel und Aktualisierungstoken.

Dienstkonten

Eine Alternative zu den oben genannten Erteilungstypen ist das Konzept der Dienstleistung Konten

Dienstkonten unterscheiden sich von den obigen Angaben dadurch, dass sie nicht für den Zugriff auf Nutzer verwendet werden. Daten: Nach der Authentifizierung werden Anfragen vom Dienstkonto im Namen des Nutzers gestellt. der Anwendung und nicht als Nutzer, der das Projekt übernehmen könnte. Wenn beispielsweise die Drive API zum Erstellen einer Datei verwendet haben, gehören zum Dienstkonto und sind für Nutzer standardmäßig nicht zugänglich Projektinhaber sind.

Beispiel einer Google Natural Language API

Die Natural Language API bietet Stimmung Analyse und Entität für Text analysieren.

In diesem Beispiel wird die Stimmung für Anzeigentext, z. B. Anzeigentitel oder Textzeile. Dies ist ein Maß für wie positiv die Botschaft ist und wie groß sie ist: Was ist besser, Wir verkaufen Torten oder Wir verkaufen die besten Kuchen in London. Jetzt kaufen!

Skript einrichten
  1. Erstellen Sie ein neues Projekt in der API Console.
  2. Natural Language aktivieren API
  3. Aktivieren Sie die Abrechnung für das Projekt.
  4. Dienst erstellen Konto. Laden Sie die JSON-Datei mit den Anmeldedaten herunter.
  5. Beispiel einfügen in ein neues Skript in Google Ads erstellen.
  6. Fügen Sie außerdem das OAuth2-Beispiel Bibliothek unterhalb des Code-Eintrag.
  7. Ersetzen Sie die erforderlichen Werte: <ph type="x-smartling-placeholder">
      </ph>
    • serviceAccount: Die E-Mail-Adresse des Dienstkontos, z. B. xxxxx@yyyy.iam.gserviceaccount.com.
    • key: Der Schlüssel aus der JSON-Datei, die beim Erstellen des Dienstes heruntergeladen wurde. Konto. Beginnt am -----BEGIN PRIVATE KEY... und endet am ...END PRIVATE KEY-----\n.

API-Antworten

APIs können Daten in verschiedenen Formaten zurückgeben. Besonders hervorzuheben sind dabei XML-Dateien, und JSON.

JSON

Die Arbeit mit JSON als Antwortformat. Es können jedoch dennoch einige Probleme auftreten.

Antwortenvalidierung

Nachdem der API-Aufruf eine erfolgreiche Antwort erhalten hat, ist normalerweise Als Nächstes konvertieren Sie den JSON-String mit JSON.parse in einen JavaScript- -Objekt enthält. An dieser Stelle ist es sinnvoll, den Fall zu handhaben, in dem das Parsing fehlgeschlagen:

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

Wenn Sie keine Kontrolle über die API haben, sollten Sie außerdem bedenken, dass die Struktur des Antwort kann sich ändern und Properties sind möglicherweise nicht mehr vorhanden:

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

Validierung

XML ist immer noch ein beliebtes Format zum Erstellen von APIs. Antwort auf einen API-Aufruf kann mit der Methode XmlService parse :

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

Während XmlService.parse Fehler in der XML-Datei erkennt und Ausnahmen auslöst Dementsprechend bietet es keine Möglichkeit, die XML-Datei anhand eines Schema.

Stammelement

Bei erfolgreichem Parsen des XML-Dokuments wird das Stammelement abgerufen. mithilfe der Methode getRootElement():

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

Namespaces

Im folgenden Beispiel wird die Sportradar API wird verwendet, um Fußballergebnisse für ausgewählte Spiele zu erhalten. Die XML-Antwort im folgenden Format:

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

Beachten Sie, wie der Namespace im Stammelement angegeben wird. Aus diesem Grund ist es erforderlich für:

  • Extrahieren Sie das Namespace-Attribut aus dem Dokument.
  • Verwenden Sie diesen Namespace beim Durchlaufen und Zugreifen auf untergeordnete Elemente.

Das folgende Beispiel zeigt, wie oben auf das Element <matches> zugegriffen wird Dokument-Snippet:

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

Werte abrufen

Anhand des Beispiels aus dem Fußballspielplan:

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

Attribute können beispielsweise abgerufen werden:

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

In einem Element enthaltener Text kann mit getText() gelesen werden. bei mehreren untergeordneten Textunterelementen eines Elements verkettet werden. Erwägen Sie mit getChildren() und Iteration über jedes untergeordnete Element, in Fällen, in denen mehrere wahrscheinlich Kinder.

Beispiel für Sportradar

Dieses umfassende Sportradar Beispiel veranschaulicht Details zu Fußballspielen, insbesondere der englischen Premier League, werden abgerufen Übereinstimmungen. Die Soccer API ist einer der zahlreichen Sportfeeds von Sportradar.

Sportradar-Konto einrichten
  1. Rufen Sie die Sportradar-Entwicklerwebsite auf.
  2. Registrieren Sie sich für ein Testkonto.
  3. Melden Sie sich nach der Registrierung in Ihrem Konto an.
  4. Rufen Sie nach der Anmeldung MyAccount auf.

Bei Sportradar werden verschiedene Sportarten in verschiedene APIs unterteilt. Zum Beispiel haben Sie erhalten möglicherweise Zugriff auf die Soccer API, aber nicht auf die Tennis API. Jedes Der von Ihnen erstellten Anwendung können verschiedene Sportarten zugeordnet werden. verschiedenen Tasten.

  1. Klicken Sie unter „Applications“ (Anwendungen) auf Create a new Application (Neue Anwendung erstellen). Anwendung bereitstellen einen Namen und eine Beschreibung eingeben und das Website-Feld ignorieren.
  2. Wähle nur die Option Neuen Schlüssel für Fußball Trial Europe v2 ausgeben aus.
  3. Klicken Sie auf Register Application (Anwendung registrieren).

Anschließend sollte eine Seite mit Ihrem neuen API-Schlüssel angezeigt werden.

  1. Fügen Sie das Beispielskript ein. in ein neues Skript in Google Ads.
  2. Ersetzen Sie den API-Schlüssel in der Liste durch den oben erhaltenen Schlüssel und bearbeiten Sie den E-Mail-Adresse ein.

Fehlerbehebung

Bei der Arbeit mit Drittanbieter-APIs können aus verschiedenen Gründen Fehler auftreten, Beispiel:

  • Clients, die Anfragen an den Server in einem Format senden, das von der API nicht erwartet wird.
  • Clients, die ein anderes Antwortformat als dem erwarteten erwarten.
  • Clients, die ungültige Tokens oder Schlüssel verwenden oder Werte als Platzhalter beibehalten.
  • Clients, die Nutzungslimits erreicht haben.
  • Clients, die ungültige Parameter angeben.

In all diesen und anderen Fällen ist ein guter erster Schritt zur Ermittlung der Ursache des Problems besteht darin, die Details der Antwort zu untersuchen, die den Fehler verursacht.

Antworten parsen

Standardmäßig wird jede Antwort, die einen Fehler (ein Statuswert Code von 400 oder mehr). vom Google Ads-Skriptmodul ausgegeben.

Um dies zu verhindern und Fehler und Fehlermeldung das Attribut muteHttpExceptions der optionalen Parameter auf UrlFetchApp.fetch. Beispiel:

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

Allgemeine Statuscodes

  • 200 OK zeigt eine erfolgreiche Ausführung an. Wenn die Antwort nicht das erwartete sollten Sie Folgendes beachten:

    • Bei einigen APIs kann angegeben werden, welche Felder und/oder das Antwortformat verwenden. Weitere Informationen hierzu finden Sie in der API-Dokumentation.
    • Eine API kann über mehrere Ressourcen verfügen, die aufgerufen werden können. Informationen hierzu finden Sie in der um zu ermitteln, ob eine andere Ressource und gibt die benötigten Daten zurück.
    • Die API hat sich möglicherweise geändert, seit der Code geschrieben wurde. Informationen hierzu finden Sie in der oder den Entwickler, um weitere Informationen zu erhalten.

  • 400 Bad Request bedeutet in der Regel, dass im Feld Formatierung oder Struktur der an den Server gesendeten Anfrage. Untersuchen Sie die und mit den API-Spezifikationen vergleichen, um sicherzustellen, Erwartungen erfüllt. Weitere Informationen finden Sie unter Anfragen überprüfen. wie die Anträge überprüft werden.

  • 401 Unauthorized bedeutet normalerweise, dass die API ohne Angabe oder Autorisierung durchgeführt.

    • Wenn die API die Basisautorisierung verwendet, prüfen Sie, ob der Authorization-Header wird erstellt und in der Anfrage bereitgestellt.
    • Wenn die API OAuth 2.0 verwendet, prüfen Sie, ob das Zugriffstoken abgerufen wurde. und als Inhabertoken bereitgestellt wird.
    • Stellen Sie bei allen anderen Abweichungen der Autorisierung sicher, dass die erforderlichen Anmeldedaten für die Anfrage bereitgestellt werden.

  • 403 Forbidden gibt an, dass der Nutzer keine Berechtigung für die Ressource hat angefordert wird.

    • Stellen Sie sicher, dass dem Nutzer die erforderlichen Berechtigungen gewährt wurden. Beispiel: Nutzerzugriff auf eine Datei in einer dateibasierten Anfrage gewähren

  • 404 Not Found bedeutet, dass die angeforderte Ressource nicht vorhanden ist.

    • Prüfen Sie, ob die für den API-Endpunkt verwendete URL korrekt ist.
    • Prüfen Sie beim Abrufen einer Ressource, ob die Ressource, auf die verwiesen wird, existiert. (z. B. wenn die Datei für eine dateibasierte API vorhanden ist).

Prüfanfragen

Die Prüfung von Anfragen ist nützlich, wenn API-Antworten darauf hinweisen, dass die Anfrage schlecht ist z. B. einen 400-Statuscode. Um Sie bei der Prüfung von Anträgen zu unterstützen, UrlFetchApp hat eine zur fetch()-Methode begleitende Methode, getRequest()

Anstatt eine Anfrage an den Server zu senden, erstellt diese Methode die Anfrage hätte gesendet werden sollen, und gibt es dann zurück. So können Nutzende Elemente der Anfrage überprüfen, um sicherzustellen, dass die Anfrage korrekt aussieht.

Wenn Formulardaten in Ihrer Anfrage beispielsweise aus vielen verketteten Strings bestehen, zusammengenommen, kann der Fehler in der Funktion liegen, die Sie zum Generieren dieses Formulars erstellt haben. Daten. Ganz einfach:

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

können Sie die Elemente der Anfrage überprüfen.

Anfragen und Antworten protokollieren

Um den gesamten Prozess der Prüfung von Anfragen und Antworten auf eine Drittanbieter-API kann die folgende Hilfsfunktion als Drop-in Ersetzen für UrlFetchApp.fetch(), um sowohl Anfragen als auch Antworten zu protokollieren.

  1. Ersetzen Sie alle Instanzen von UrlFetchApp.fetch() in Ihrem Code durch logUrlFetch().

  2. Fügen Sie die folgende Funktion am Ende des Skripts hinzu.

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

Beim Ausführen des Skripts werden Details zu allen Anfragen und Antworten in um die Fehlerbehebung zu vereinfachen.