Drittanbieter-APIs

Eine leistungsstarke Funktion von Google Ads-Skripts ist die Einbindung von Daten und Diensten von Drittanbieter-APIs.

In diesem Leitfaden werden die folgenden Konzepte behandelt, die Ihnen beim Schreiben von Skripts zur Verbindung mit anderen Diensten helfen können:

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

Daten mit UrlFetchApp abrufen

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

Das folgende Beispiel zeigt, wie Wetterdaten von OpenWeatherMap abgerufen werden. Wir haben uns wegen des relativ einfachen Autorisierungsschemas und der API für OpenWeatherMap entschieden.

Anfrage stellen

In der OpenWeatherMap-Dokumentation 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 stellt unser erstes Autorisierungsbeispiel dar: Der Parameter apikey ist erforderlich und der Wert ist für jeden Nutzer eindeutig. Sie erhalten diesen Schlüssel, wenn Sie sich anmelden.

Nach der Registrierung kann eine Anfrage mit dem Schlüssel so ausgegeben 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 JSON-Text, der in das Protokollierungsfenster von Google Ads-Skripts geschrieben wird.

Der nächste Schritt besteht darin, dieses Format in ein Format zu konvertieren, das in Ihrem Skript verwendet werden kann.

JSON-Daten

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

Wenn Sie einen JSON-String, wie den von OpenWeatherMap zurückgegebenen, wieder in ein JavaScript-Objekt konvertieren möchten, verwenden Sie die integrierte Methode JSON.parse. Ausgehend vom Beispiel oben:

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 zur Arbeit mit API-Antworten in verschiedenen Formaten finden Sie im Abschnitt Antworten parsen.

Fehlerbehandlung

Die Fehlerbehandlung ist ein wichtiger Aspekt, wenn Sie in Ihren Skripts mit APIs von Drittanbietern arbeiten, da diese APIs sich häufig häufig ändern und unerwartete Antwortwerte generieren. Beispiele:

  • 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 ohne vorherige Ankündigung geändert werden.

HTTP-Statuscodes

Aufgrund unerwarteter Antworten sollten Sie den HTTP-Statuscode prüfen. Wenn ein HTTP-Fehlercode auftritt, löst UrlFetchApp standardmäßig eine Ausnahme aus. Um dieses Verhalten zu ändern, müssen Sie einen optionalen Parameter wie im folgenden Beispiel übergeben:

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 Skripts auswirken können. Wenn beispielsweise das im OpenWeatherMap-Beispiel zurückgegebene Attribut name in locationName geändert wird, schlagen Skripts fehl, die dieses Attribut verwenden.

Aus diesem Grund kann es hilfreich sein, zu testen, ob die zurückgegebene Struktur wie erwartet funktioniert. 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, in dem OpenWeatherMap nur Daten abgerufen hat In der Regel verwenden API-Aufrufe, die den Status auf dem Remoteserver nicht ändern, die Methode HTTP GET.

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

Die Verwendung von POST-Aufrufen mit UrlFetchApp wird im folgenden Beispiel veranschaulicht, wie die Integration mit Slack, einer kollaborativen Messaging-Anwendung, zum Senden einer Slack-Nachricht an Slack-Nutzer und -Gruppen veranschaulicht wird.

Slack einrichten

In dieser Anleitung wird davon ausgegangen, dass Sie bereits für ein Slack-Konto registriert sind.

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, mit der Sie Nachrichten an Ihr Team senden können. Sie wird als eingehender Webhook bezeichnet.

Richten Sie einen eingehenden Webhook ein. Klicken Sie dazu auf Add Inbound Webhooks Integration (Integration eingehender Webhooks hinzufügen) und folgen Sie der Anleitung. Dabei sollte eine URL für die Nachrichtenfunktion ausgegeben werden.

POST-Anfrage stellen

Wenn Sie den eingehenden Webhook eingerichtet haben, müssen Sie für eine POST-Anfrage im Parameter options, der an UrlFetchApp.fetch übergeben wird, einige zusätzliche Attribute verwenden:

  • method: Wie bereits erwähnt, ist der Standardwert GET, aber hier wird er ü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 im JSON-Format serialisiertes Objekt, wie in der Slack-Dokumentation beschrieben. Dazu wird die Methode JSON.stringify verwendet und Content-Type ist auf application/json festgelegt.

      // 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, wie geringfügig eingehende Nachrichten in Slack aktiviert werden müssen. Ein erweitertes Beispiel veranschaulicht das Erstellen und Senden eines Berichts zur Kampagnenleistung an eine Gruppe sowie einige Formatierungs- und Anzeigeoptionen.

Eingehende Nachricht

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

Formulardaten

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

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

  • 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 konvertiert:

    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 beim Senden von POST-Anfragen Formulardaten verwendet werden. Daher ist diese automatische Konvertierung von JavaScript-Objekten in Formulardaten sinnvoll.

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

Zum Erstellen einer authentifizierten Anfrage sind die folgenden Schritte erforderlich:

  1. Bilden Sie die Passphrase durch Verbinden des Nutzernamens und des Passworts mit einem Doppelpunkt, z. B. username:password.
  2. Codieren Sie die Passphrase mit Base64. Beispiel: username:password wird zu dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Hängen Sie einen Authorization-Header im Format Authorization: Basic <encoded passphrase> an die Anfrage an.

Im folgenden Snippet sehen Sie, 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);

Plivo

Plivo ist ein Dienst, der das Senden und Empfangen von SMS über die API vereinfacht. Dieses Beispiel veranschaulicht das Senden von Nachrichten.

  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 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, damit Sie bei Fehlern benachrichtigt 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, die als Absender angezeigt wird, als auch die Nummer des Empfängers hinzu.
  7. Aktualisieren Sie PLIVO_SRC_PHONE_NUMBER im Skript auf eine der soeben registrierten Sandbox-Nummern. Dieser sollte den internationalen Ländercode 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 über die API vereinfacht. Dieses Beispiel veranschaulicht das Senden von Nachrichten.

  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 in der Kontokonsole angezeigt werden.
  4. Ersetzen Sie TWILIO_SRC_PHONE_NUMBER durch die Nummer aus dem Dashboard. Dies ist die Nummer, die von Twilio zum Senden von Nachrichten autorisiert wurde.

OAuth 1.0

Viele gängige Dienste verwenden OAuth zur Authentifizierung. OAuth gibt es in mehreren Varianten.

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

Hintergrundinformationen zu OAuth 1.0 finden Sie im OAuth Core-Leitfaden. Siehe insbesondere 6. Authentifizierung mit OAuth Bei vollem dreibeinigem OAuth 1.0 sieht der Vorgang so aus:

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

Damit Drittanbieterdienste OAuth 1.0 ohne Nutzerinteraktion verwenden können (z. B. für Google Ads-Skripts), sind die Schritte 1, 2 und 3 nicht möglich. Daher stellen einige Dienste ein Zugriffstoken über ihre Konfigurationskonsole aus, wodurch die Anwendung direkt mit Schritt 4 fortfahren kann. Dies wird als einbeiniges OAuth 1.0 bezeichnet.

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 ist in der Regel Folgendes erforderlich:

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

oauth 2.0

OAuth 2.0 wird in gängigen APIs verwendet, um den Zugriff auf Nutzerdaten zu ermöglichen. Der Inhaber eines Kontos für einen bestimmten Drittanbieterdienst erteilt bestimmten Anwendungen die Berechtigung, auf Nutzerdaten zuzugreifen. Der Inhaber hat folgende Vorteile:

  • Er muss seine Kontoanmeldedaten nicht an die Anwendung weitergeben.
  • Kann steuern, welche Anwendungen individuell und in welchem Umfang Zugriff auf die Daten haben. (Der Zugriff kann beispielsweise schreibgeschützt oder nur für einen Teil der Daten sein.)

So verwenden Sie OAuth 2.0-fähige Dienste in Google Ads-Skripts:

Außerhalb Ihres Skripts

Erteilen Sie Google Ads-Skripts Zugriff auf Ihre Nutzerdaten über die Drittanbieter-API. In den meisten Fällen müssen Sie dazu eine Anwendung in der Konsole des Drittanbieterdienstes einrichten. Diese Anwendung stellt Ihr Google Ads-Skript dar.

Sie geben an, welche Zugriffsrechte die Anwendung von Google Ads Script erhalten soll. In der Regel 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.

Im Skript

Autorisierung mit dem Remoteserver Abhängig vom Berechtigungstyp, den der Server zugelassen hat, sind andere Schritte erforderlich, die als Ablauf bezeichnet werden. All diese Schritte 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 bei jeder Anfrage.

Autorisierungsabläufe

Jede Art der Bewilligung und der entsprechende Ablauf sind auf unterschiedliche Nutzungsszenarien zugeschnitten. Wenn ein Nutzer beispielsweise an einer interaktiven Sitzung teilnimmt, wird ein anderer Ablauf verwendet, im Gegensatz zu einem Szenario, bei dem eine Anwendung ohne Nutzer im Hintergrund ausgeführt werden muss.

API-Anbieter entscheiden, welche Berechtigungstypen sie akzeptieren. Dies gibt Aufschluss darüber, wie der Nutzer mit der Integration seiner API vorgeht.

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 dargestellt, wie die Authentifizierung für die verschiedenen Ablauftypen erfolgt. Jede dieser Methoden gibt ein Objekt zurück, das das Zugriffstoken abruft, speichert und authentifizierte Anfragen ermöglicht.

Das allgemeine Nutzungsmuster 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 Gewährung von Clientanmeldedaten ist eine der einfacheren Formen des OAuth2-Vorgangs, bei denen die Anwendung eine für die Anwendung eindeutige ID und ein Secret austauscht. Im Gegenzug wird im Gegenzug ein zeitlich begrenztes Zugriffstoken ausgestellt.

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

Erteilung von Aktualisierungstokens

Die Erteilung von Aktualisierungstokens ähnelt der Erteilung von Client-Anmeldedaten, 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 Erteilung von Aktualisierungstokens besteht darin, dass die für die Erteilung von Clientanmeldedaten erforderlichen Details aus der Anwendungskonfiguration (z. B. im Steuerfeld des Dienstes) stammen, das Aktualisierungstoken jedoch im Rahmen eines komplexeren Ablaufs gewährt wird, z. B. bei der Erteilung eines Autorisierungscodes, für die eine Nutzerinteraktion erforderlich ist:

Autorisierungscode

Aktualisierungstoken über OAuth Playground abrufen

Der OAuth2 Playground bietet eine UI, in der der Nutzer die Autorisierungscode-Gewährung durchgehen kann, um ein Aktualisierungstoken abzurufen.

Mit der Schaltfläche „Einstellungen“ oben rechts können Sie alle Parameter definieren, die im OAuth-Ablauf verwendet werden sollen, darunter:

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

OAuth-Playground

Aktualisierungstoken über ein Skript abrufen

Eine skriptbasierte Alternative zum Abschließen des Ablaufs ist im Beispiel zur Generierung von Aktualisierungstokens verfügbar.

Nutzung des Aktualisierungstokens

Nachdem die erste Autorisierung durchgeführt wurde, können Dienste ein Aktualisierungstoken ausgeben, das dann ähnlich wie der Ablauf für Clientanmeldedaten verwendet werden kann. Hier 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 wird von einem Skript ein Bericht generiert und zurückgegeben. In der Search Ads 360 API-Referenz finden Sie ausführliche Informationen zu weiteren möglichen Aktionen.

Skript erstellen
  1. Erstellen Sie ein neues Projekt in der API-Konsole und rufen Sie eine Client-ID, einen Clientschlüssel und ein Aktualisierungstoken ab. Folgen Sie dazu der Anleitung im DoubleClick-Leitfaden und achten Sie darauf, dass Sie die DoubleClick Search API aktivieren.
  2. Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
  3. Fügen Sie die OAuth2-Beispielbibliothek unter der Codeliste ein.
  4. Ändern Sie das Skript so, dass es die korrekten Werte für Client-ID, Clientschlüssel und Aktualisierungstoken enthält.

Beispiel für die Apps Script Execution API

In diesem Beispiel wird die Ausführung einer Funktion in Apps Script mithilfe der Apps Script Execution API veranschaulicht. So kann Apps Script über Google Ads-Skripts aufgerufen werden.

Apps Script-Script erstellen

Erstellen Sie ein neues Skript. Im folgenden Beispiel werden 10 Dateien aus 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 Skript.
  2. Klicken Sie auf Ressourcen > Cloud Platform-Projekt.
  3. Klicken Sie auf den Projektnamen, um die API-Konsole aufzurufen.
  4. Rufen Sie APIs und 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 das Menü Anmeldedaten.
  7. Kehren Sie zu Ihrem Skript zurück und veröffentlichen Sie das Skript zur Ausführung. Klicken Sie dazu auf Publish > Deploy as API Executable (Veröffentlichen > Als API Executable bereitstellen).
Google Ads-Skript erstellen
  1. Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
  2. Fügen Sie außerdem die Beispiel-OAuth2-Bibliothek unter der Codeliste ein.
  3. Ändern Sie das Skript so, dass es die korrekten 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 darin, dass sie nicht für den Zugriff auf Nutzerdaten verwendet werden: Nach der Authentifizierung werden Anfragen vom Dienstkonto im Namen der Anwendung und nicht als der Eigentümer des Projekts gestellt. Wenn das Dienstkonto beispielsweise die Drive API zum Erstellen einer Datei verwendet, gehört diese zum Dienstkonto und ist standardmäßig nicht für den Projektinhaber zugänglich.

Beispiel für eine Google Natural Language API

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

In diesem Beispiel wird die Stimmung des Anzeigentexts berechnet, einschließlich Anzeigentitel oder Textzeile. Damit wird gemessen, wie positiv und intensiv die Botschaft ist: Wir verkaufen Torten oder Wir verkaufen die besten Torten in London. Jetzt kaufen!?

Skript einrichten
  1. Erstellen Sie ein neues Projekt in der API-Konsole.
  2. Aktivieren Sie die Natural Language API.
  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 Beispielskript in ein neues Skript in Google Ads ein.
  6. Fügen Sie außerdem die Beispiel-OAuth2-Bibliothek unter der Codeliste 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 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

Nach dem Erhalt einer erfolgreichen Antwort beim Aufruf der API besteht der typische nächste Schritt darin, den JSON-String in ein JavaScript-Objekt mit JSON.parse zu konvertieren. An dieser Stelle empfiehlt es sich, den Fall zu handhaben, dass das Parsing 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 kontrollieren, sollten Sie außerdem berücksichtigen, dass sich die Struktur der Antwort ändern kann und die 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

Validierung

XML ist immer noch ein beliebtes Format zum Erstellen von APIs. Eine Antwort auf einen 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 löst entsprechend Ausnahmen aus, bietet jedoch keine Möglichkeit, die XML-Datei anhand eines Schemas zu validieren.

Stammelement

Nach dem erfolgreichen Parsen des XML-Dokuments 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 xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

Beachten Sie, wie der Namespace im Stammelement angegeben ist. Aus diesem Grund ist es notwendig,

  • Extrahieren Sie das Namespace-Attribut aus dem Dokument.
  • Verwenden Sie diesen Namespace, wenn Sie untergeordnete Elemente durchlaufen und darauf zugreifen.

Das folgende Beispiel zeigt, wie Sie auf das Element <matches> im obigen Dokument-Snippet zugreifen:

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

Ausgehend vom Beispiel aus dem Fußballspielplan:

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

Attribute können abgerufen werden, z. B.:

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

Der in einem Element enthaltene Text kann mit getText() gelesen werden. Er wird jedoch verkettet, wenn mehrere untergeordnete Textelemente eines Elements vorhanden sind. In Fällen, in denen mehrere untergeordnete Textelemente wahrscheinlich sind, empfiehlt es sich, getChildren() zu verwenden und über jedes untergeordnete Element zu iterieren.

Beispiel für Sportradar

Dieses vollständige Sportradar-Beispiel zeigt das Abrufen von Details von Fußballspielen, insbesondere Spiele der englischen Premier League. Die Soccer API ist einer von vielen Sportfeeds, die von Sportradar angeboten wird.

Sportradar-Konto einrichten
  1. Rufen Sie die Entwicklerwebsite von Sportradar 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.

Sportradar trennt verschiedene Sportarten in verschiedene APIs. Sie können beispielsweise Zugriff auf die Soccer API erwerben, aber nicht auf die Tennis API. Jeder von Ihnen erstellten Anwendung können verschiedene Sportarten und unterschiedliche Schlüssel zugeordnet sein.

  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 die Option Neuen Schlüssel für Soccer Trial Europe v2 ausstellen aus.
  3. Klicken Sie auf Register Application (Anwendung registrieren).

Nach erfolgreicher Ausführung 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 oben abgerufenen 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 erwartete.
  • Clients, die ungültige Tokens oder Schlüssel verwenden oder Werte als Platzhalter belassen.
  • Kunden, die die Nutzungslimits erreichen
  • Clients, die ungültige Parameter angeben.

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

Antworten parsen

Standardmäßig wird jede Antwort, bei der ein Fehler zurückgegeben wird, also der Statuscode 400 oder höher, vom Google Ads-Skriptmodul ausgegeben.

Um dieses Verhalten zu verhindern und die Fehler- und Fehlermeldung zu überprü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...
}

Allgemeine Statuscodes

  • 200 OK zeigt an, dass der Vorgang erfolgreich war. Wenn die Antwort nicht die erwarteten Daten enthält, bedenken Sie Folgendes:

    • Bei einigen APIs können Sie angeben, welche Felder und/oder Antwortformate verwendet werden sollen. Weitere Informationen hierzu finden Sie in der API-Dokumentation.
    • Eine API kann mehrere Ressourcen haben, die aufgerufen werden können. In der Dokumentation können Sie nachlesen, ob eine andere Ressource besser geeignet ist, um die benötigten Daten zurückzugeben.
    • Die API hat sich seit dem Schreiben des Codes möglicherweise geändert. Wenden Sie sich an die Dokumentation oder an den Entwickler, um weitere Informationen zu erhalten.

  • 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 ohne Autorisierung aufgerufen oder erfolgreich ausgeführt wird.

    • Wenn die API die Basisautorisierung verwendet, prüfen Sie, ob der Header Authorization in der Anfrage erstellt und angegeben wird.
    • Wenn die API OAuth 2.0 verwendet, achten Sie darauf, dass das Zugriffstoken abgerufen und als Inhabertoken bereitgestellt wird.
    • Für alle anderen Varianten der Autorisierung 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.

    • Überprüfen Sie, ob dem Nutzer die erforderlichen Berechtigungen erteilt wurden, z. B. für den 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 Ressource vorhanden ist, auf die verwiesen wird (z. B. wenn 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 nicht richtig formatiert ist, z. B. der Statuscode 400. Zum leichteren Prüfen von Anfragen hat UrlFetchApp eine Companion-Methode zur fetch()-Methode namens getRequest().

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

Wenn Formulardaten in Ihrer Anfrage beispielsweise aus vielen miteinander verketteten Strings bestehen, liegt der Fehler möglicherweise in der Funktion, die Sie zum Generieren dieser Formulardaten erstellt haben. 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 Anforderung überprüfen.

Anfragen und Antworten protokollieren

Sie können die folgende Hilfsfunktion als Drop-in-Ersatz für UrlFetchApp.fetch() verwenden, um sowohl Anfragen als auch Antworten zu protokollieren. So können Sie den gesamten Prozess der Prüfung von Anfragen und Antworten an eine Drittanbieter-API unterstützen.

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

  2. Fügen Sie die folgende Funktion am Ende Ihres Skripts 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;
}

Beim Ausführen des Skripts werden Details zu allen Anfragen und Antworten in der Konsole protokolliert, was die Fehlerbehebung erleichtert.