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
UrlFetchAppfü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 StandardwertGET. Hier wird er jedoch überschrieben und aufPOSTgesetzt.payload: Dies sind die Daten, die im Rahmen derPOST-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 undContent-Typeaufapplication/jsongesetzt.// 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.

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
payloadein String ist, wird das Stringargument als Text der Anfrage gesendet. Wenn
payloadein 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-Typefür die Anfrage aufapplication/x-www-form-urlencodedfestgelegt.
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.

Anfrage erstellen
Die folgenden Schritte sind erforderlich, um eine authentifizierte Anfrage zu erstellen:
- Bilden Sie die Passphrase, indem Sie den Nutzernamen und das Passwort mit einem Doppelpunkt verbinden, z. B.
username:password. - Codieren Sie die Passphrase im Base64-Format. Aus
username:passwordwird beispielsweisedXNlcm5hbWU6cGFzc3dvcmQ=. - Fügen Sie der Anfrage einen
Authorization-Header im FormatAuthorization: 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.
- Registrieren Sie sich bei Plivo.
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Ersetzen Sie die Werte für
PLIVO_ACCOUNT_AUTHIDundPLIVO_ACCOUNT_AUTHTOKENdurch die Werte aus dem Verwaltungs-Dashboard. - Geben Sie Ihre E-Mail-Adresse wie im Skript angegeben ein, um Benachrichtigungen zu Fehlern zu erhalten.
- 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.
- Fügen Sie sowohl die Nummer, die als Absender angezeigt wird, als auch die Empfängernummer hinzu.
- Aktualisieren Sie
PLIVO_SRC_PHONE_NUMBERim Script auf eine der gerade registrierten Sandbox-Nummern. Diese sollte die internationale Landesvorwahl enthalten, z. B.447777123456fü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.
- Registrieren Sie sich bei Twillio.
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Ersetzen Sie die Werte
TWILIO_ACCOUNT_SIDundTWILIO_ACCOUNT_AUTHTOKENdurch die Werte, die auf der Kontoseite der Console angezeigt werden. - Ersetzen Sie
TWILIO_SRC_PHONE_NUMBERdurch 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:
- Die Anwendung („Consumer“) erhält ein Anfragetoken.
- Der Nutzer autorisiert das Anfragetoken.
- Die Anwendung tauscht das Anfragetoken gegen ein Zugriffstoken aus.
- 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.

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.

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

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

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
- 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.
- Fügen Sie das [Beispielskript][search-ads-360-example] in ein neues Skript in Google Ads ein.
- Fügen Sie die [OAuth2-Beispielbibliothek][oauth20-library-example] unter der Codeliste ein.
- Ä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
- Speichern Sie das Script.
- Klicken Sie auf Ressourcen > Cloud Platform-Projekt.
- Klicken Sie auf den Projektnamen, um die Google Cloud Console aufzurufen.
- Rufen Sie APIs & Dienste auf.
- Aktivieren Sie die entsprechenden APIs, in diesem Fall die Drive API und die Apps Script Execution API.
- Erstellen Sie OAuth-Anmeldedaten über den Menüpunkt Anmeldedaten.
- Veröffentlichen Sie das Skript in Ihrem Skript zur Ausführung über Veröffentlichen > Als ausführbare API bereitstellen.
Google Ads-Script erstellen
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Fügen Sie außerdem die [OAuth2-Beispielbibliothek][oauth20-library-example] unter der Codeauflistung ein.
- Ä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
- Erstellen Sie ein neues Projekt in der Google Cloud Console.
- Aktivieren Sie die [Natural Language API][natural-language-api].
- Aktivieren Sie die Abrechnung für das Projekt.
- [Dienstkonto erstellen][create-service-account]. Laden Sie die JSON-Datei mit den Anmeldedaten herunter.
- Fügen Sie das [Beispielskript][natural-language-example] in ein neues Skript in Google Ads ein.
- Fügen Sie außerdem die [OAuth2-Beispielbibliothek][oauth20-library-example] unter der Codeauflistung ein.
- 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
- Rufen Sie die Sportradar-Entwicklerwebsite auf.
- Registrieren Sie sich für ein Testkonto.
- Melden Sie sich nach der Registrierung in Ihrem Konto an.
- 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.
- Klicken Sie unter „Anwendungen“ auf Neue Anwendung erstellen. Geben Sie der Anwendung einen Namen und eine Beschreibung und ignorieren Sie das Feld „Website“.
- Wählen Sie nur Neuen Schlüssel für Soccer Trial Europe v2 ausstellen aus.
- Klicken Sie auf Anwendung registrieren.
Wenn der Vorgang erfolgreich war, sollte eine Seite mit Ihrem neuen API-Schlüssel angezeigt werden.
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- 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 OKweist 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 Requestbedeutet 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 Unauthorizedbedeutet 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
Authorizationin 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.
- Wenn die API die Basisautorisierung verwendet, muss der Header
403 Forbiddengibt 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 Foundbedeutet, 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.
Ersetzen Sie alle Instanzen von
UrlFetchApp.fetch()in Ihrem Code durchlogUrlFetch().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