Drittanbieter-APIs

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

In diesem Leitfaden werden die folgenden Konzepte behandelt, die Ihnen beim Schreiben von Skripts zum Herstellen einer Verbindung zu anderen Diensten helfen können:

  • HTTP-Anfragen stellen: Verwendung von UrlFetchApp für den Zugriff auf externe APIs.
  • Authentifizierung: Wir behandeln einige gängige Authentifizierungsszenarien.
  • Antworten parsen: Hier erfahren Sie, wie Sie zurückgegebene JSON- und XML-Daten verarbeiten.

Außerdem stellen wir Beispiele für eine Reihe gängiger APIs bereit, die diese Konzepte veranschaulichen.

Daten mit UrlFetchApp abrufen

UrlFetchApp bietet die Hauptfunktionen, die für die Interaktion mit Drittanbieter-APIs erforderlich sind.

Im folgenden Beispiel werden Wetterdaten von OpenWeatherMap abgerufen. Wir haben uns für OpenWeatherMap entschieden, da das Autorisierungsschema und die API relativ einfach sind.

Anfrage stellen

In der Dokumentation von OpenWeatherMap wird das Format für die Abfrage des aktuellen Wetters so angegeben:

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

Die URL ist unser erstes Beispiel für die Autorisierung: Der Parameter apikey ist erforderlich und der Wert ist für jeden Nutzer eindeutig. Diesen Schlüssel erhalten Sie, 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());

Wenn Sie diesen Code ausführen, wird ein langer JSON-String in das Logging-Fenster in Google Ads-Scripts geschrieben.

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

JSON-Daten

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

Wenn Sie einen JSON-String, wie er von OpenWeatherMap zurückgegeben wird, wieder in ein JavaScript-Objekt konvertieren möchten, verwenden Sie die integrierte Methode JSON.parse. Fortsetzung des vorherigen 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 mit dem Attribut name.

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

Fehlerbehandlung

Die Fehlerbehandlung ist ein wichtiger Aspekt bei der Arbeit mit Drittanbieter-APIs in Ihren Skripts, da sich diese 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

Da unerwartete Antworten möglich sind, sollten Sie den HTTP-Statuscode prüfen. Standardmäßig löst UrlFetchApp eine Ausnahme aus, wenn ein HTTP-Fehlercode auftritt. Wenn Sie dieses Verhalten ändern möchten, müssen Sie 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, werden Sie möglicherweise nicht sofort über Änderungen informiert, die sich auf Ihre Skripts auswirken könnten. Wenn beispielsweise die im OpenWeatherMap-Beispiel zurückgegebene Property name in locationName geändert wird, schlagen Skripts fehl, die diese Property verwenden.

Aus diesem Grund kann es nützlich sein, zu testen, ob die zurückgegebene Struktur wie erwartet ist, 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

Im Einführungsbeispiel mit OpenWeatherMap wurden nur Daten abgerufen. In der Regel verwenden API-Aufrufe, die den Status auf dem Remote-Server nicht ändern, die Methode HTTP GET.

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

Zur Veranschaulichung der Verwendung von POST-Aufrufen mit UrlFetchApp zeigt das folgende Beispiel die Integration in Slack, eine Messaging-Anwendung für die Zusammenarbeit, 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, ein Token abzurufen, um das Senden von Nachrichten zu ermöglichen. Slack stellt eine eindeutige URL bereit, über die Sie Nachrichten an Ihr Team senden können. Diese wird als eingehender Webhook bezeichnet.

Richten Sie einen eingehenden Webhook ein, indem Sie auf Add Incoming WebHooks Integration klicken und der Anleitung folgen. Der Prozess sollte eine URL für die Nachrichtenübermittlung ausgeben.

POST-Anfrage stellen

Nachdem Sie den eingehenden Webhook eingerichtet haben, müssen Sie für eine POST-Anfrage einige zusätzliche Attribute im Parameter options 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 sollen. In diesem Beispiel erwartet Slack ein Objekt, das im JSON-Format serialisiert ist, wie in der Slack-Dokumentation beschrieben. Dazu wird die Methode [JSON.stringify][json-stringify-url] 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

Das vorherige Beispiel zeigt den Mindestcode, der erforderlich ist, um eingehende Nachrichten in Slack zu aktivieren. 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 vorherigen Beispiel wurde ein JSON-String als payload-Attribut für die POST-Anfrage verwendet.

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

  • Wenn payload ein String ist, wird das Stringargument als Text der Anfrage gesendet.
  • 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 umgewandelt:

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

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

Bei einigen APIs müssen Formulardaten verwendet werden, wenn POST-Anfragen gesendet werden. Daher ist es hilfreich, diese automatische Konvertierung von JavaScript-Objekten in Formulardaten im Hinterkopf zu behalten.

HTTP-Basisauthentifizierung

Die HTTP-Basisauthentifizierung ist eine der einfachsten Formen 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. Bilden Sie die Passphrase, indem Sie den Nutzernamen und das Passwort mit einem Doppelpunkt verbinden, z. B. username:password.
  2. Codieren Sie die Passphrase im Base64-Format. Aus username:password wird beispielsweise dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Fügen Sie der Anfrage einen Authorization-Header im Format Authorization: Basic <encoded passphrase> hinzu.

Das folgende Snippet zeigt, wie Sie das in Google Ads-Scripts erreichen:

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 seine 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 Skript in Google Ads ein.
  3. Ersetzen Sie die Werte für PLIVO_ACCOUNT_AUTHID und PLIVO_ACCOUNT_AUTHTOKEN durch die Werte aus dem Verwaltungs-Dashboard.
  4. Geben Sie Ihre E-Mail-Adresse wie im Skript angegeben ein, um Benachrichtigungen zu Fehlern zu erhalten.
  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, die als Absender angezeigt wird, als auch die Empfängernummer hinzu.
  7. Aktualisieren Sie PLIVO_SRC_PHONE_NUMBER im Script auf eine der gerade registrierten Sandbox-Nummern. Diese sollte die internationale Landesvorwahl enthalten, 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 mit seiner API ermöglicht. In diesem Beispiel wird das Senden von Nachrichten veranschaulicht.

  1. Registrieren Sie sich bei Twillio.
  2. Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
  3. Ersetzen Sie die Werte TWILIO_ACCOUNT_SID und TWILIO_ACCOUNT_AUTHTOKEN durch die Werte, die auf der Kontoseite der Console 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 zur Authentifizierung. OAuth gibt es in verschiedenen Varianten und Versionen.

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

Hintergrundinformationen zu OAuth 1.0 finden Sie im OAuth Core-Leitfaden. Siehe insbesondere 6. Authentifizierung mit OAuth. Bei der vollständigen dreibeinigen OAuth 1.0-Authentifizierung 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 für Google Ads-Scripts erforderlich wäre), sind die 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 normalerweise als Anwendung interpretiert. In der Regel müssen Sie auf der Seite mit den Konsolen- oder Verwaltungseinstellungen für den Dienst Folgendes tun:

  • Richten Sie eine Anwendungskonfiguration ein, die das Script darstellt.
  • Geben Sie an, welche Berechtigungen dem Skript gewährt werden.
  • Rufen Sie den Consumer-Key, das Consumer-Secret, das Zugriffstoken und das Zugriffs-Secret für die Verwendung mit One-Legged OAuth ab.

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, dass der Eigentümer:

  • muss seine Kontoanmeldedaten nicht an die Anwendung weitergeben.
  • Sie können individuell festlegen, welche Anwendungen Zugriff auf die Daten haben und in welchem Umfang. (Beispielsweise kann der Zugriff nur auf Lesen oder nur auf eine Teilmenge der Daten beschränkt sein.)

Wenn Sie OAuth 2.0-fähige Dienste in Google Ads-Scripts verwenden möchten, müssen Sie die folgenden Schritte ausführen:

Außerhalb Ihres Scripts

Autorisieren Sie Google Ads-Scripts, ü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 stellt Ihr Script dar.

Sie legen fest, welche Zugriffsrechte die Anwendung für Google Ads-Skripts erhalten soll. In der Regel wird ihr eine Client-ID zugewiesen. So können Sie über OAuth 2.0 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 Genehmigungstyp müssen unterschiedliche Schritte, ein sogenannter Ablauf, ausgeführt werden. Alle führen jedoch letztendlich dazu, dass ein Zugriffstoken ausgestellt wird, 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 Genehmigungstyp und der entsprechende Ablauf sind für unterschiedliche Nutzungsszenarien geeignet. Beispielsweise wird ein anderer Ablauf verwendet, wenn ein Nutzer an einer interaktiven Sitzung teilnimmt, als wenn eine Anwendung im Hintergrund ausgeführt werden muss, ohne dass ein Nutzer anwesend ist.

API-Anbieter entscheiden, welche Genehmigungstypen sie akzeptieren. Dies bestimmt, wie der Nutzer die API einbindet.

Implementierung

Bei allen 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.

Eine Beispielbibliothek veranschaulicht, wie Sie sich für die verschiedenen Ablauftypen authentifizieren. Jede dieser Methoden gibt ein Objekt zurück, das das Zugriffstoken abruft und speichert und authentifizierte Anfragen ermöglicht.

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

Die [Gewährung von Clientanmeldedaten][client-credentials-rfc] ist eine der einfacheren Formen des OAuth2-Ablaufs, bei der die Anwendung eine ID und ein Secret, die für die Anwendung eindeutig sind, gegen die Ausstellung eines zeitlich begrenzten Zugriffstokens austauscht.

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

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

Aktualisierungstoken

Aktualisierungstoken abrufen

Der Unterschied zur Gewährung des Aktualisierungstokens besteht darin, dass die für die Gewährung von Clientanmeldedaten erforderlichen Details aus der Anwendungskonfiguration stammen (z. B. im Steuerfeld des Dienstes), während das Aktualisierungstoken im Rahmen eines komplexeren Ablaufs gewährt wird, z. B. einer [Autorisierungscodegewährung][authorization-code-rfc], die eine Nutzerinteraktion erfordert:

Autorisierungscode

Aktualisierungstoken über den OAuth Playground abrufen

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

Über die Schaltfläche „Einstellungen“ oben rechts können Sie alle Parameter für den OAuth-Vorgang festlegen, 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

Nutzung von Aktualisierungstokens

Nach der ersten Autorisierung können Dienste ein Aktualisierungstoken ausstellen, das dann ähnlich wie der Client-Anmeldedatenfluss verwendet werden kann:

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 Script einen Bericht und gibt ihn zurück. Ausführliche Informationen zu anderen Aktionen, die ausgeführt werden können, finden Sie in der Search Ads 360 API-Referenz.

Script erstellen
  1. Erstellen Sie ein neues Projekt in der Google Cloud Console und rufen Sie eine Client-ID, einen Clientschlüssel und ein Aktualisierungstoken ab. Folgen Sie dazu der Anleitung im Search Ads 360-Leitfaden und aktivieren Sie die Search Ads 360 API.
  2. Fügen Sie das [Beispielskript][search-ads-360-example] in ein neues Skript in Google Ads ein.
  3. Fügen Sie die [OAuth2-Beispielbibliothek][oauth20-library-example] unter der Codeliste ein.
  4. Ändern Sie das Script so, dass es die richtigen Werte für die Client-ID, den Clientschlüssel und das Aktualisierungstoken enthält.

Beispiel für die Apps Script Execution API

In diesem Beispiel wird gezeigt, wie eine Funktion in Apps Script mit der Apps Script Execution API ausgeführt wird. So können Sie Apps Script über Google Ads-Scripts aufrufen.

Apps Script-Skript erstellen

Neues Script erstellen 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 Google Cloud Console aufzurufen.
  4. Rufen Sie APIs & Dienste auf.
  5. Aktivieren Sie die entsprechenden APIs, in diesem Fall die Drive API und die Apps Script Execution API.
  6. Erstellen Sie OAuth-Anmeldedaten über den Menüpunkt Anmeldedaten.
  7. Veröffentlichen Sie das Skript in Ihrem Skript zur Ausführung über Veröffentlichen > Als ausführbare API bereitstellen.
Google Ads-Script erstellen
  1. Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
  2. Fügen Sie außerdem die [OAuth2-Beispielbibliothek][oauth20-library-example] unter der Codeauflistung ein.
  3. Ändern Sie das Script so, dass es die richtigen Werte für die Client-ID, den Clientschlüssel und das Aktualisierungstoken enthält.

Dienstkonten

Eine Alternative zu Genehmigungstypen ist das Konzept von Dienstkonten.

Dienstkonten unterscheiden sich von Genehmigungstypen darin, dass sie nicht für den Zugriff auf Nutzerdaten verwendet werden: Nach der Authentifizierung werden Anfragen vom Dienstkonto im Namen der Anwendung gestellt, nicht als der Nutzer, der möglicherweise der Inhaber des Projekts ist. Wenn das Dienstkonto beispielsweise die Drive API zum Erstellen einer Datei verwendet, 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][natural-language-api-docs] bietet [Sentimentanalyse][sentiment-analysis-api-docs] und [Entitätsanalyse][entity-analysis-api-docs] für Text.

In diesem Beispiel wird die Berechnung der [Stimmung][sentiment-api-docs] für Anzeigentext veranschaulicht, einschließlich Anzeigentitel oder Textzeile. So lässt sich messen, wie positiv die Botschaft ist und wie stark sie wirkt: Was ist besser, Wir verkaufen Kuchen oder Wir verkaufen die besten Kuchen in London? Jetzt kaufen!?

Script einrichten
  1. Erstellen Sie ein neues Projekt in der Google Cloud Console.
  2. Aktivieren Sie die [Natural Language API][natural-language-api].
  3. Aktivieren Sie die Abrechnung für das Projekt.
  4. [Dienstkonto erstellen][create-service-account]. Laden Sie die JSON-Datei mit den Anmeldedaten herunter.
  5. Fügen Sie das [Beispielskript][natural-language-example] in ein neues Skript in Google Ads ein.
  6. Fügen Sie außerdem die [OAuth2-Beispielbibliothek][oauth20-library-example] unter der Codeauflistung 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 als Antwortformat in der Regel einfacher zu verwenden als XML. Es können jedoch weiterhin 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 zu konvertieren. 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 die API nicht von Ihnen kontrolliert wird, sollten Sie außerdem bedenken, dass sich die Struktur der Antwort ändern kann und Attribute möglicherweise nicht mehr vorhanden sind:

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

Mit XmlService können Ihre Skripts Daten aus XML-Antworttexten parsen und extrahieren.

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 im XML-Code und löst entsprechende Ausnahmen aus, bietet aber nicht die Möglichkeit, den XML-Code 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 das folgende Format:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

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, wenn Sie untergeordnete Elemente durchlaufen und darauf zugreifen.

Im folgenden Beispiel wird gezeigt, wie Sie auf das Element <schedule> zugreifen und im vorherigen Dokument-Snippet nach den untergeordneten Elementen <sport_event> suchen:

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

Werte abrufen

Angenommen, es liegt dieses Beispiel aus dem Fußballspielplan vor:

<sport_event_status status="..." ... />

Attribute können beispielsweise so abgerufen werden:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

In einem Element enthaltener Text kann mit getText() gelesen werden. Wenn ein Element mehrere untergeordnete Textelemente hat, werden diese jedoch verkettet. In Fällen, in denen mehrere untergeordnete Textelemente wahrscheinlich sind, sollten Sie getChildren() verwenden und jedes untergeordnete Element durchlaufen.

Sportradar-Beispiel

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

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 Mein Konto auf.

Sportradar trennt verschiedene Sportarten in verschiedene APIs. Sie können beispielsweise den Zugriff auf die Soccer API, aber nicht auf die Tennis API erwerben. Jeder von Ihnen erstellten Anwendung können unterschiedliche Sportarten und Schlüssel 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ählen Sie 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 Skript in Google Ads ein.
  2. Ersetzen Sie den API-Schlüssel im Eintrag durch den neu ausgestellten Schlüssel und bearbeiten Sie das Feld für die E-Mail-Adresse.

Fehlerbehebung

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

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

In all diesen und anderen Fällen ist es ein guter erster Schritt, die Details der Antwort zu untersuchen, die den Fehler verursacht, um die Ursache des Problems zu ermitteln.

Antworten parsen

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

Um dieses Verhalten zu verhindern und den Fehler und die Fehlermeldung zu prüfen, setzen Sie 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...
}

Häufige Statuscodes

  • 200 OK weist auf einen Erfolg hin. Wenn die Antwort nicht die erwarteten Daten enthält, beachten Sie Folgendes:

    • Bei einigen APIs können Sie angeben, welche Felder, welches Antwortformat oder beides verwendet werden soll. Weitere Informationen finden Sie in der API-Dokumentation.
    • Eine API kann mehrere Ressourcen haben, die aufgerufen werden können. In der Dokumentation finden Sie Informationen dazu, ob eine andere Ressource besser geeignet ist und die erforderlichen Daten zurückgibt.
    • Die API hat sich möglicherweise geändert, seit der Code geschrieben wurde. Weitere Informationen finden Sie in der Dokumentation oder beim Entwickler.
  • 400 Bad Request bedeutet in der Regel, dass die Formatierung oder Struktur der an den Server gesendeten Anfrage nicht korrekt ist. 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 der 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 Basisautorisierung verwendet, muss der Header Authorization in der Anfrage erstellt und angegeben werden.
    • Wenn die API OAuth 2.0 verwendet, muss das Zugriffstoken abgerufen und als Inhabertoken bereitgestellt werden.
    • Achten Sie bei anderen Autorisierungsvarianten darauf, dass die erforderlichen Anmeldedaten für die Anfrage angegeben werden.
  • 403 Forbidden gibt an, dass der Nutzer keine Berechtigung für die angeforderte Ressource hat.

    • Achten Sie darauf, dass 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.
    • Wenn Sie eine Ressource abrufen, prüfen Sie, ob die referenzierte Ressource vorhanden ist (z. B. ob die Datei für eine dateibasierte API vorhanden ist).

Anfragen prüfen

Das Prüfen von Anfragen ist nützlich, wenn API-Antworten darauf hinweisen, dass die Anfrage fehlerhaft ist, z. B. ein 400-Statuscode. Zur Untersuchung von Anfragen gibt es in UrlFetchApp eine Begleitmethode zur Methode fetch(), die getRequest(url, params) heißt.

Anstatt eine Anfrage an den Server zu senden, wird mit dieser Methode die Anfrage erstellt, die gesendet worden wäre, und dann zurückgegeben. So kann der Nutzer Elemente der Anfrage prüfen, um sicherzustellen, dass die Anfrage korrekt ist.

Wenn die Formulardaten in Ihrer Anfrage beispielsweise aus vielen verketteten Strings bestehen, liegt der Fehler möglicherweise in der Funktion, die Sie zum Generieren dieser Formulardaten erstellt haben. Einfach ausgedrückt:

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

Um den gesamten Prozess der Prüfung von Anfragen und Antworten an eine Drittanbieter-API zu unterstützen, kann die folgende Hilfsfunktion als direkter Ersatz für UrlFetchApp.fetch() verwendet werden, 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 am Ende des Scripts die folgende Funktion 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;
    }
    

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

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities