Drittanbieter-APIs

Eine nützliche Funktion von Google Ads-Scripts ist die Möglichkeit, Daten und Dienste von Drittanbieter-APIs zu integrieren.

In diesem Leitfaden werden die folgenden Konzepte behandelt, die Ihnen beim Schreiben von Scripts für die Verbindung zu anderen Diensten helfen können:

  • HTTP-Anfragen stellen: Informationen zum Zugriff auf externe APIs mit UrlFetchApp
  • Authentifizierung: Wir behandeln einige gängige Authentifizierungsszenarien.
  • Antworten parsen: Hier erfahren Sie, wie zurückgegebene JSON- und XML-Daten verarbeitet werden.

Außerdem finden Sie Beispiele für eine Reihe beliebter APIs, die diese Konzepte veranschaulichen.

Daten mit UrlFetchApp abrufen

UrlFetchApp bietet die grundlegenden Funktionen, die für die Interaktion mit APIs von Drittanbietern erforderlich sind.

Im folgenden Beispiel wird gezeigt, wie Wetterdaten von OpenWeatherMap abgerufen werden. Wir haben OpenWeatherMap aufgrund des relativ einfachen Autorisierungsschemas und der API ausgewählt.

Anfrage stellen

In der OpenWeatherMap-Dokumentation wird das Format für die Abfrage des aktuellen Wetters folgendermaßen angegeben:

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

Die URL ist unser erstes Beispiel für eine Autorisierung: Der Parameter apikey ist erforderlich und der Wert ist für jeden Nutzer eindeutig. Sie erhalten diesen Schlüssel, wenn Sie sich registrieren.

Nach der Registrierung kann eine Anfrage mit dem Schlüssel so gestellt 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());

Die Ausführung dieses Codes führt zu einem langen String aus JSON-Text, der in das Protokollfenster in Google Ads-Scripts geschrieben wird.

Im nächsten Schritt wird das Bild in ein Format konvertiert, das in Ihrem Script verwendet werden kann.

JSON-Daten

Viele APIs geben Antworten im JSON-Format zurück. Dies stellt eine einfache Serialization von JavaScript-Objekten dar, sodass Objekte, Arrays und einfache Typen als Strings dargestellt und übertragen werden können.

Wenn Sie einen JSON-String wie den von OpenWeatherMap zurückgegebenen in ein JavaScript-Objekt konvertieren möchten, verwenden Sie die integrierte Methode JSON.parse. Fortsetzung des obigen Beispiels:

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

Die JSON.parse-Methode wandelt den String in ein Objekt mit der Eigenschaft name um.

Weitere Informationen zum Arbeiten mit API-Antworten in verschiedenen Formaten findest du im Abschnitt Antworten parsen.

Fehlerbehandlung

Die Fehlerbehandlung ist ein wichtiger Aspekt bei der Arbeit mit Drittanbieter-APIs in Ihren Scripts, da sich Drittanbieter-APIs häufig ändern und unerwartete Antwortwerte generieren, z. B.:

  • Die URL oder die Parameter für die API können sich ohne Ihr Wissen ändern.
  • Ihr API-Schlüssel (oder andere Nutzeranmeldedaten) kann ablaufen.
  • Das Format der Antwort kann sich ohne Vorankündigung ändern.

HTTP-Statuscodes

Aufgrund der Möglichkeit unerwarteter Antworten sollten Sie den HTTP-Statuscode prüfen. Standardmäßig löst UrlFetchApp eine Ausnahme aus, wenn ein HTTP-Fehlercode auftritt. Wenn du dieses Verhalten ändern möchtest, musst du einen optionalen Parameter übergeben, wie im folgenden 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 APIs von Drittanbietern ändern, sind Entwickler oft nicht sofort über Änderungen informiert, die sich auf ihre Scripts auswirken könnten. Wenn beispielsweise die im OpenWeatherMap-Beispiel zurückgegebene name-Eigenschaft in locationName geändert wird, funktionieren Scripts, die diese Eigenschaft verwenden, nicht.

Aus diesem Grund kann es sinnvoll sein, zu testen, ob die zurückgegebene Struktur wie erwartet ist, z. B.:

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

Im Einführungsbeispiel mit OpenWeatherMap wurden nur Daten abgerufen. Normalerweise wird für API-Aufrufe, die den Status auf dem Remote-Server nicht ändern, die Methode HTTP GET verwendet.

Die Methode GET ist die Standardmethode für UrlFetchApp. Für einige API-Aufrufe, z. B. für Aufrufe eines Dienstes, der SMS-Nachrichten sendet, sind jedoch andere Methoden wie POST oder PUT erforderlich.

Im folgenden Beispiel wird die Integration mit Slack, einer Messaging-Anwendung für die Zusammenarbeit, veranschaulicht, um eine Slack-Nachricht an Slack-Nutzer und -Gruppen zu senden.POSTUrlFetchApp

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 auch hier erforderlich, ein Token zu erhalten, um Nachrichten senden zu können. Slack stellt eine eindeutige URL bereit, über die Sie Nachrichten an Ihr Team senden können. Diese URL wird als eingehender Webhook bezeichnet.

Richten Sie einen eingehenden Webhook ein. Klicken Sie dazu auf Add incoming Webhooks integration (Integration eingehender Webhooks hinzufügen) und folgen Sie der Anleitung. Der Vorgang sollte eine URL für die Nachrichtenausgabe ausgeben.

POST-Anfrage stellen

Nachdem du deinen Eingangs-Webhook eingerichtet hast, musst du für eine POST-Anfrage nur einige zusätzliche Eigenschaften im options-Parameter verwenden, der an UrlFetchApp.fetch übergeben wird:

  • method: Wie bereits erwähnt, ist der Standardwert GET. Hier wird er jedoch überschrieben und auf POST gesetzt.

  • payload: Dies sind die Daten, die im Rahmen der POST-Anfrage an den Server gesendet werden. In diesem Beispiel erwartet Slack ein Objekt, das wie in der Slack-Dokumentation beschrieben in JSON-Format serialisiert ist. Dazu wird die Methode JSON.stringify verwendet und Content-Type 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);

Erweitertes Slack-Beispiel

Im Beispiel oben ist das Minimum zu sehen, das für eingehende Nachrichten in Slack erforderlich ist. In einem erweiterten Beispiel wird das Erstellen und Senden eines Berichts zur Kampagnenleistung an eine Gruppe sowie einige Formatierungs- und Anzeigeoptionen veranschaulicht.

Eingehende Nachricht

Weitere Informationen zu Slack-Nachrichten finden Sie in der Slack-Dokumentation unter Nachrichtenformatierung.

Formulardaten

Im Beispiel oben wurde ein JSON-String als payload-Attribut für die POST-Anfrage verwendet.

Je nach Format von payload verwendet UrlFetchApp unterschiedliche Ansätze zum Erstellen der POST-Anfrage:

  • Wenn payload ein String ist, wird das Stringargument als Textkörper der Anfrage gesendet.

  • Wenn payload ein Objekt ist, z. B. eine Wertekarte:

    {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 gesetzt.

Bei einigen APIs müssen beim Senden von POST-Anfragen Formulardaten verwendet werden. Daher ist diese automatische Umwandlung von JavaScript-Objekten in Formulardaten nützlich.

HTTP-Basisauthentifizierung

Die HTTP-Basisauthentifizierung ist eine der einfachsten Formen der Authentifizierung und wird von vielen APIs verwendet.

Die Authentifizierung erfolgt, indem in jeder Anfrage ein codierter Nutzername und ein Passwort an die HTTP-Header angehängt werden.

HTTP-Basisauthentifizierung

Anfrage erstellen

Für eine authentifizierte Anfrage sind die folgenden Schritte erforderlich:

  1. Bilden Sie die Passphrase, indem Sie den Nutzernamen und das Passwort durch einen Doppelpunkt verbinden, z. B. username:password.
  2. Codieren Sie die Passphrase mit Base64. Aus username:password wird beispielsweise dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Hängen Sie der Anfrage einen Authorization-Header im Format Authorization: Basic <encoded passphrase> an.

Im folgenden Snippet wird gezeigt, wie das in Google Ads-Scripts funktioniert:

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

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

Plivo

Plivo ist ein Dienst, der das Senden und Empfangen von SMS-Nachrichten über die API ermöglicht. In diesem Beispiel wird das Senden von Nachrichten veranschaulicht.

  1. Registrieren Sie sich bei Plivo.
  2. Fügen Sie das Beispielskript in ein neues Script in Google Ads ein.
  3. Ersetzen Sie die Werte für PLIVO_ACCOUNT_AUTHID und PLIVO_ACCOUNT_AUTHTOKEN durch die Werte aus dem Dashboard für die Verwaltung.
  4. Fügen Sie Ihre E-Mail-Adresse ein, wie im Script angegeben, um bei Fehlern benachrichtigt zu werden.
  5. Wenn Sie Plivo verwenden möchten, müssen Sie entweder Nummern kaufen oder dem Testkonto Nummern hinzufügen. Fügen Sie Sandbox-Nummern hinzu, die mit dem Testkonto verwendet werden können.
  6. Fügen Sie sowohl die Nummer hinzu, die als Absender angezeigt werden soll, als auch die Nummer des Empfängers.
  7. Aktualisieren Sie PLIVO_SRC_PHONE_NUMBER im Script auf eine der gerade registrierten Sandbox-Nummern. Dazu gehört auch der internationale Ländercode, z. B. 447777123456 für eine Nummer im Vereinigten Königreich.

Twilio

Twilio ist ein weiterer Dienst, der das Senden und Empfangen von SMS-Nachrichten über seine API vereinfacht. In diesem Beispiel wird das Senden von Nachrichten veranschaulicht.

  1. Registrieren Sie sich bei Twillio.
  2. Fügen Sie das Beispielskript in ein neues Script in Google Ads ein.
  3. Ersetzen Sie die Werte TWILIO_ACCOUNT_SID und TWILIO_ACCOUNT_AUTHTOKEN durch die Werte, die auf der Konsolenseite des Kontos angezeigt werden.
  4. Ersetzen Sie TWILIO_SRC_PHONE_NUMBER durch die Nummer aus dem Dashboard. Dies ist die von Twilio autorisierte Nummer zum Senden von Nachrichten.

OAuth 1.0

Viele beliebte Dienste verwenden OAuth für die Authentifizierung. OAuth gibt es in verschiedenen Varianten und Versionen.

Während ein Nutzer bei der HTTP-Basisauthentifizierung nur einen Nutzernamen und ein Passwort hat, können Drittanbieteranwendungen mit OAuth über Anmeldedaten, die für diese Drittanbieteranwendung spezifisch sind, Zugriff auf das Konto und die Daten eines Nutzers erhalten. Außerdem ist der Umfang des Zugriffs für jede Anwendung spezifisch.

Weitere Informationen zu OAuth 1.0 finden Sie im OAuth Core-Leitfaden. Lesen Sie insbesondere den Abschnitt 6. Authentifizierung mit OAuth Bei der vollständigen dreigliedrigen OAuth 1.0-Autorisierung läuft der Prozess so ab:

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

Wenn Drittanbieterdienste OAuth 1.0 ohne Nutzerinteraktion verwenden sollen (wie es beispielsweise bei Google Ads-Scripts erforderlich ist), sind Schritte 1, 2 und 3 nicht möglich. Daher geben einige Dienste ein Zugriffstoken über ihre Konfigurationskonsole aus, sodass die Anwendung direkt mit Schritt 4 fortfahren kann. Dies wird als einbeiniges OAuth 1.0 bezeichnet.

OAuth1

OAuth 1.0 in Google Ads-Scripts

Bei Google Ads-Scripts wird jedes Script in der Regel als Anwendung interpretiert. Auf der Seite „Konsole/Verwaltungseinstellungen“ für den Dienst müssen Sie in der Regel Folgendes tun:

  • Richten Sie eine Anwendungskonfiguration ein, um das Script darzustellen.
  • Geben Sie an, welche Berechtigungen auf das Script angewendet werden.
  • Consumer-Key, Consumer-Secret, Zugriffstoken und Zugriffssecret für die Verwendung mit OAuth mit nur einer Autorisierungsstufe abrufen

oauth 2.0

OAuth 2.0 wird in gängigen APIs verwendet, um Zugriff auf Nutzerdaten zu gewähren. Der Inhaber eines Kontos für einen bestimmten Drittanbieterdienst gewährt bestimmten Anwendungen die Berechtigung, auf Nutzerdaten zuzugreifen. Die Vorteile sind:

  • Muss seine Kontoanmeldedaten nicht an die Anwendung weitergeben.
  • Sie können festlegen, welche Anwendungen auf die Daten zugreifen können und in welchem Umfang. Der gewährte Zugriff kann beispielsweise Lesezugriff oder nur Zugriff auf einen Teil der Daten sein.

Wenn Sie OAuth 2.0-kompatible Dienste in Google Ads-Scripts verwenden möchten, sind mehrere Schritte erforderlich:

Außerhalb deines Scripts

Geben Sie Google Ads-Scripts die Berechtigung, über die Drittanbieter-API auf Ihre Nutzerdaten zuzugreifen. In den meisten Fällen müssen Sie dazu eine Anwendung in der Konsole des Drittanbieterdienstes einrichten. Diese Anwendung steht für Ihr Google Ads-Script.

Sie legen fest, welche Zugriffsrechte der Anwendung des Google Ads-Scripts gewährt werden sollen. Normalerweise wird ihr eine Client-ID zugewiesen. So können Sie über OAuth 2 steuern, welche Anwendungen Zugriff auf Ihre Daten im Drittanbieterdienst haben und welche Aspekte dieser Daten sie sehen oder ändern können.

In Ihrem Script

Mit dem Remote-Server autorisieren Je nach dem vom Server zugelassenen Grant-Typ müssen unterschiedliche Schritte ausgeführt werden, die als Ablauf bezeichnet werden. Letztendlich wird jedoch immer ein Zugriffstoken ausgegeben, das für diese Sitzung für alle nachfolgenden Anfragen verwendet wird.

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

Autorisierungsabläufe

Jeder Berechtigungstyp und der entsprechende Ablauf eignen sich für unterschiedliche Anwendungsfälle. So wird beispielsweise ein anderer Ablauf verwendet, wenn ein Nutzer an einer interaktiven Sitzung teilnimmt, im Gegensatz zu einem Szenario, in dem eine Anwendung im Hintergrund ausgeführt werden muss, ohne dass ein Nutzer anwesend ist.

API-Anbieter entscheiden, welche Arten von Berechtigungen sie akzeptieren. Dies bestimmt, wie der Nutzer mit der Integration seiner API fortfährt.

Implementierung

Bei allen verschiedenen OAuth-Abläufen besteht das Ziel darin, ein Zugriffstoken zu erhalten, das dann für den Rest der Sitzung zur Authentifizierung von Anfragen verwendet werden kann.

In einer Beispielbibliothek wird veranschaulicht, wie sich für jeden Ablauftyp authentifizieren lässt. Jede dieser Methoden gibt ein Objekt zurück, das das Zugriffstoken abrufen und speichern sowie authentifizierte Anfragen ermöglichen kann.

Das allgemeine Nutzungsmuster ist:

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

Clientanmeldedaten-Grant

Die Berechtigungsart „Clientanmeldedaten“ ist eine der einfacheren Formen des OAuth2-Ablaufs, bei dem die Anwendung eine eindeutige ID und ein geheimes Passwort für die Ausstellung eines zeitlich begrenzten Zugriffstokens eintauscht.

Clientanmeldedaten

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

Aktualisierungstoken-Berechtigung

Die Aktualisierung des Tokens ähnelt der Gewährung von Clientanmeldedaten, da eine einfache Anfrage an den Server ein Zugriffstoken zurückgibt, das in der Sitzung verwendet werden kann.

Aktualisierungstoken

Aktualisierungstoken abrufen

Der Unterschied bei der Aktualisierungstoken-Gewährung besteht darin, dass die für die Erteilung von Anmeldedaten für einen Client erforderlichen Details aus der Anwendungskonfiguration stammen (z. B. im Steuerfeld des Dienstes). Das Aktualisierungstoken wird hingegen im Rahmen eines komplexeren Ablaufs gewährt, z. B. bei der Erteilung eines Autorisierungscodes, für den eine Nutzerinteraktion erforderlich ist:

Autorisierungscode

Aktualisierungstoken mit dem OAuth Playground abrufen

Der OAuth2-Playground bietet eine Benutzeroberfläche, über die der Nutzer die Autorisierungscode-Genehmigung durchlaufen kann, um ein Aktualisierungstoken zu erhalten.

Über die Schaltfläche „Einstellungen“ rechts oben können Sie alle Parameter für den OAuth-Vorgang definieren, darunter:

  • Autorisierungsendpunkt: Wird als Start des Autorisierungsablaufs verwendet.
  • Token-Endpunkt: Wird mit dem Aktualisierungstoken verwendet, um ein Zugriffstoken abzurufen.
  • Client-ID und Secret: Anmeldedaten für die Anwendung.

OAuth Playground

Aktualisierungstoken mit einem Script abrufen

Eine scriptbasierte Alternative zum Ausführen des Ablaufs finden Sie im Beispiel zur Generierung von Aktualisierungstokens.

Verwendung von Aktualisierungstokens

Nach der Erstautorisierung können Dienste ein Aktualisierungstoken ausstellen, das dann ähnlich wie der Ablauf für Clientanmeldedaten verwendet werden kann. Unten finden Sie zwei Beispiele:

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

Beispiel für Search Ads 360

Search Ads 360 ist ein Beispiel für eine API, die mit einem Aktualisierungstoken verwendet werden kann. In diesem Beispiel generiert und gibt ein Script einen Bericht zurück. Ausführliche Informationen zu anderen möglichen Aktionen finden Sie in der Search Ads 360 API-Referenz.

Script erstellen
  1. Erstellen Sie ein neues Projekt in der API Console und rufen Sie eine Client-ID, ein Client-Secret und ein Aktualisierungstoken ab. Folgen Sie dazu der Anleitung im DoubleClick-Leitfaden und aktivieren Sie die DoubleClick Search API.
  2. Fügen Sie das Beispielskript in ein neues Script in Google Ads ein.
  3. Fügen Sie die Beispiel-OAuth2-Bibliothek unter dem Code-Listeneintrag ein.
  4. Ändern Sie das Script so, dass es die richtigen Werte für Client-ID, Clientschlüssel und Aktualisierungstoken enthält.

Beispiel für die Apps Script Execution API

In diesem Beispiel wird veranschaulicht, wie eine Funktion in Apps Script mithilfe der Apps Script Execution API ausgeführt wird. So können Apps Script-Funktionen von Google Ads-Scripts aufgerufen werden.

Apps Script-Script erstellen

Erstellen Sie ein neues Script. Im folgenden Beispiel werden 10 Dateien aus Google Drive aufgelistet:

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 Script.
  2. Klicken Sie auf Ressourcen > Cloud Platform-Projekt.
  3. Klicken Sie auf den Projektnamen, um die API Console aufzurufen.
  4. Gehen Sie zu APIs und Dienste.
  5. Aktivieren Sie die entsprechenden APIs, in diesem Fall die Drive API und die Apps Script Execution API.
  6. Erstellen Sie OAuth-Anmeldedaten über das Menüelement Anmeldedaten.
  7. Veröffentlichen Sie das Script im Skript unter Veröffentlichen > Als ausführbare API veröffentlichen zur Ausführung.
Google Ads-Script erstellen
  1. Fügen Sie das Beispielskript in ein neues Script in Google Ads ein.
  2. Fügen Sie außerdem die Beispiel-OAuth2-Bibliothek unter dem Code-Listeneintrag ein.
  3. Ändern Sie das Script so, dass es die richtigen Werte für Client-ID, Clientschlüssel und Aktualisierungstoken enthält.

Dienstkonten

Eine Alternative zu den oben genannten Berechtigungstypen ist das Konzept von Dienstkonten.

Dienstkonten unterscheiden sich von den oben genannten Konten dadurch, dass sie nicht zum Zugriff auf Nutzerdaten verwendet werden: Nach der Authentifizierung werden Anfragen vom Dienstkonto im Namen der Anwendung gesendet, nicht als Nutzer, der möglicherweise Inhaber des Projekts ist. Wenn das Dienstkonto beispielsweise die Drive API verwendet, um eine Datei zu erstellen, gehört diese dem Dienstkonto und ist standardmäßig nicht für den Inhaber des Projekts zugänglich.

Beispiel für die Google Natural Language API

Die Natural Language API bietet eine Sentimentanalyse und eine Entitätsanalyse für Text.

In diesem Beispiel wird die Berechnung des Stimmungsgehalts für Anzeigentext veranschaulicht, einschließlich Anzeigentitel oder Textzeile. Dies gibt Aufschluss darüber, wie positiv die Botschaft ist und wie groß sie ist: Was ist besser: Wir verkaufen Kuchen oder Wir verkaufen die besten Kuchen in London. Jetzt kaufen!?

Script einrichten
  1. Neues Projekt in der API Console erstellen
  2. Natural Language API aktivieren
  3. Aktivieren Sie die Abrechnung für das Projekt.
  4. Erstellen Sie ein Dienstkonto. Laden Sie die JSON-Datei mit den Anmeldedaten herunter.
  5. Fügen Sie das Beispielscript in ein neues Script in Google Ads ein.
  6. Fügen Sie außerdem die Beispiel-OAuth2-Bibliothek unter dem Code-Listeneintrag ein.
  7. Ersetzen Sie die erforderlichen Werte:
    • 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 Dienstkontos heruntergeladen wurde. Beginnt am -----BEGIN PRIVATE KEY... und endet am ...END PRIVATE KEY-----\n.

API-Antworten

APIs können Daten in verschiedenen Formaten zurückgeben. Die bekanntesten davon sind XML und JSON.

JSON

JSON ist in der Regel einfacher als XML als Antwortformat zu verwenden. Es können jedoch immer noch Probleme auftreten.

Antwortenvalidierung

Nachdem Sie eine erfolgreiche Antwort vom API-Aufruf erhalten haben, besteht der nächste Schritt in der Regel darin, den JSON-String mit JSON.parse in ein JavaScript-Objekt umzuwandeln. An dieser Stelle ist es sinnvoll, den Fall zu behandeln, in dem das Parsen fehlschlägt:

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

Wenn Sie die API nicht selbst verwalten, kann sich die Struktur der Antwort ä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 nach wie vor ein beliebtes Format für die Erstellung von APIs. Eine Antwort von einem API-Aufruf kann mit der Methode XmlService parse geparst werden:

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

XmlService.parse erkennt zwar Fehler in der XML-Datei und wirft entsprechende Ausnahmen, bietet aber keine Möglichkeit, die XML-Datei anhand eines Schemas zu validieren.

Stammelement

Wenn das XML-Dokument erfolgreich geparst wurde, wird das Stammelement mit der Methode getRootElement() abgerufen:

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

Namespaces

Im folgenden Beispiel wird die Sportradar API verwendet, um Fußballergebnisse für ausgewählte Spiele abzurufen. Die XML-Antwort hat folgendes 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 ist. Daher ist Folgendes erforderlich:

  • Extrahieren Sie das Namespace-Attribut aus dem Dokument.
  • Verwenden Sie diesen Namespace beim Durchlaufen und Abrufen von untergeordneten Elementen.

Im folgenden Beispiel wird gezeigt, wie im obigen Dokument-Snippet auf das Element <matches> zugegriffen wird:

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

Angenommen, es liegt dieser Beispielstream vor:

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

Folgende Attribute können abgerufen werden:

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

Text in einem Element kann mit getText() gelesen werden. Wenn ein Element jedoch mehrere untergeordnete Textelemente hat, werden diese zusammengeführt. Wenn Sie davon ausgehen, dass mehrere untergeordnete Textelemente vorhanden sind, sollten Sie getChildren() verwenden und über jedes untergeordnete Element iterieren.

Beispiel für Sportradar

In diesem vollständigen Sportradar-Beispiel wird das Abrufen von Details zu Fußballspielen, insbesondere zu Spielen der englischen Premier League, veranschaulicht. Die Soccer API ist einer von vielen Sportfeeds, die von Sportradar angeboten werden.

Sportradar-Konto einrichten
  1. Rufe die Sportradar-Entwicklerwebsite auf.
  2. Registrieren Sie sich für ein Testkonto.
  3. Melden Sie sich in Ihrem Konto an.
  4. Melden Sie sich an und rufen Sie MyAccount auf.

Sportradar unterscheidet verschiedene Sportarten in verschiedenen APIs. Du kannst beispielsweise Zugriff auf die Fußball-API, aber nicht auf die Tennis-API erwerben. Jede von Ihnen erstellte Anwendung kann verschiedenen Sportarten und verschiedenen Schlüsseln zugeordnet werden.

  1. Klicken Sie unter „Anwendungen“ auf Neue Anwendung erstellen. Geben Sie der Anwendung einen Namen und eine Beschreibung und ignorieren Sie das Feld „Website“.
  2. Wähle nur Neuen Schlüssel für Soccer Trial Europe v2 ausstellen aus.
  3. Klicken Sie auf Anwendung registrieren.

Wenn der Vorgang erfolgreich war, sollte eine Seite mit Ihrem neuen API-Schlüssel angezeigt werden.

  1. Fügen Sie das Beispielskript in ein neues Script in Google Ads ein.
  2. Ersetzen Sie den API-Schlüssel im Eintrag durch den oben erhaltenen Schlüssel und bearbeiten Sie das Feld für die E-Mail-Adresse.

Fehlerbehebung

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

  • Clients, die Anfragen an den Server in einem von der API nicht erwarteten Format senden.
  • Clients erwarten ein anderes Antwortformat als das, das tatsächlich verwendet wird.
  • Clients, die ungültige Tokens oder Schlüssel verwenden oder Werte als Platzhalter lassen
  • Kunden, die die Nutzungslimits erreichen
  • Clients, die ungültige Parameter angeben

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

Antworten analysieren

Standardmäßig wird jede Antwort, die einen Fehler zurückgibt (Statuscode 400 oder höher), von der Google Ads-Scripts-Engine geworfen.

Um dieses Verhalten zu verhindern und den Fehler und die Fehlermeldung prüfen zu können, legen Sie die muteHttpExceptions-Eigenschaft der optionalen Parameter auf UrlFetchApp.fetch fest. Beispiel:

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

Gängige Statuscodes

  • 200 OK steht für Erfolg. Wenn die Antwort nicht die erwarteten Daten enthält, beachten Sie Folgendes:

    • Bei einigen APIs können Sie angeben, welche Felder und/oder welches Antwortformat verwendet werden soll. Weitere Informationen finden Sie in der API-Dokumentation.
    • Eine API kann mehrere Ressourcen haben, die aufgerufen werden können. Lesen Sie in der Dokumentation nach, ob eine andere Ressource besser geeignet ist und die benötigten Daten zurückgibt.
    • Die API hat sich möglicherweise seit dem Schreiben des Codes geändert. Weitere Informationen finden Sie in der Dokumentation oder beim Entwickler.

  • 400 Bad Request bedeutet in der Regel, dass bei der Formatierung oder Struktur der an den Server gesendeten Anfrage etwas nicht stimmt. Prüfen Sie die Anfrage und vergleichen Sie sie mit den API-Spezifikationen, um sicherzustellen, dass sie den Erwartungen entspricht. Weitere Informationen zum Prüfen von Anfragen finden Sie unter Anfragen prüfen.

  • 401 Unauthorized bedeutet in der Regel, dass die API aufgerufen wird, ohne dass eine Autorisierung bereitgestellt oder erfolgreich durchgeführt wurde.

    • Wenn die API die Basisauthentifizierung verwendet, muss der Authorization-Header erstellt und in der Anfrage angegeben werden.
    • Wenn die API OAuth 2.0 verwendet, muss das Zugriffstoken abgerufen und als Inhabertoken bereitgestellt werden.
    • Bei anderen Autorisierungsvarianten müssen die erforderlichen Anmeldedaten für die Anfrage angegeben werden.

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

    • Prüfen Sie, ob dem Nutzer die erforderlichen Berechtigungen gewährt wurden, z. B. Zugriff auf eine Datei in einer dateibasierten Anfrage.

  • 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 referenzierte Ressource vorhanden ist (z. B. ob die Datei für eine dateibasierte API vorhanden ist).

Anfragen prüfen

Die Prüfung von Anfragen ist nützlich, wenn API-Antworten darauf hinweisen, dass die Anfrage fehlerhaft ist, z. B. durch einen Statuscode 400. Zur Prüfung von Anfragen gibt es für UrlFetchApp eine Begleitmethode zur fetch()-Methode, die getRequest() heißt.

Anstatt eine Anfrage an den Server zu senden, erstellt diese Methode die Anfrage, die gesendet worden wäre, und gibt sie zurück. So können Nutzer Elemente der Anfrage prüfen, um sicherzustellen, dass sie korrekt ist.

Wenn die Formulardaten in Ihrer Anfrage beispielsweise aus vielen zusammenhängenden Strings bestehen, liegt der Fehler möglicherweise in der Funktion, die Sie zum Generieren dieser Formulardaten erstellt haben. In der einfachsten Form:

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 prüfen.

Anfragen und Antworten protokollieren

Die folgende Hilfsfunktion kann als Ersatz für UrlFetchApp.fetch() verwendet werden, um sowohl Anfragen als auch Antworten zu protokollieren. So können Sie Anfragen und Antworten an eine Drittanbieter-API einfacher prüfen.

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

  2. Fügen Sie die folgende Funktion am Ende des Scripts ein.

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

Wenn Sie das Script ausführen, werden Details zu allen Anfragen und Antworten in der Konsole protokolliert, was die Fehlerbehebung erleichtert.