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 StandardwertGET
, aber hier wird er überschrieben und aufPOST
gesetzt.payload
: Dies sind die Daten, die im Rahmen derPOST
-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 MethodeJSON.stringify
verwendet undContent-Type
ist aufapplication/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.
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 aufapplication/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.
Anfrage erstellen
Zum Erstellen einer authentifizierten Anfrage sind die folgenden Schritte erforderlich:
- Bilden Sie die Passphrase durch Verbinden des Nutzernamens und des Passworts mit einem Doppelpunkt, z. B.
username:password
. - Codieren Sie die Passphrase mit Base64. Beispiel:
username:password
wird zudXNlcm5hbWU6cGFzc3dvcmQ=
. - Hängen Sie einen
Authorization
-Header im FormatAuthorization: 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.
- Registrieren Sie sich bei Plivo.
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Ersetzen Sie die Werte
PLIVO_ACCOUNT_AUTHID
undPLIVO_ACCOUNT_AUTHTOKEN
durch die Werte aus dem Verwaltungs-Dashboard. - Geben Sie Ihre E-Mail-Adresse wie im Skript angegeben ein, damit Sie bei Fehlern benachrichtigt werden.
- 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 Nummer des Empfängers hinzu.
- 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.
- Registrieren Sie sich bei Twillio.
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Ersetzen Sie die Werte
TWILIO_ACCOUNT_SID
undTWILIO_ACCOUNT_AUTHTOKEN
durch die Werte, die in der Kontokonsole angezeigt werden. - 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:
- Die Anwendung („Nutzer“) erhält ein Anfrage-Token.
- Der Nutzer autorisiert das Anfragetoken.
- Die Anwendung tauscht das Anforderungs-Token gegen ein Zugriffstoken aus.
- 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.
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.
// 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 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:
- 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.
- 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
- 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.
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Fügen Sie die OAuth2-Beispielbibliothek unter der Codeliste ein.
- Ä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
- Speichern Sie das Skript.
- Klicken Sie auf Ressourcen > Cloud Platform-Projekt.
- Klicken Sie auf den Projektnamen, um die API-Konsole aufzurufen.
- Rufen Sie APIs und Dienste auf.
- Aktivieren Sie die entsprechenden APIs, in diesem Fall die Drive API und die Apps Script Execution API.
- Erstellen Sie OAuth-Anmeldedaten über das Menü Anmeldedaten.
- 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
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Fügen Sie außerdem die Beispiel-OAuth2-Bibliothek unter der Codeliste ein.
- Ä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
- Erstellen Sie ein neues Projekt in der API-Konsole.
- Aktivieren Sie die Natural Language API.
- Aktivieren Sie die Abrechnung für das Projekt.
- Erstellen Sie ein Dienstkonto. Laden Sie die JSON-Datei mit den Anmeldedaten herunter.
- Fügen Sie das Beispielskript in ein neues Skript in Google Ads ein.
- Fügen Sie außerdem die Beispiel-OAuth2-Bibliothek unter der Codeliste 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 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
- Rufen Sie die Entwicklerwebsite von Sportradar auf.
- Registrieren Sie sich für ein Testkonto.
- Melden Sie sich nach der Registrierung in Ihrem Konto an.
- 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.
- Klicken Sie unter „Anwendungen“ auf Neue Anwendung erstellen. Geben Sie der Anwendung einen Namen und eine Beschreibung und ignorieren Sie das Feld „Website“.
- Wähle nur die Option Neuen Schlüssel für Soccer Trial Europe v2 ausstellen aus.
- Klicken Sie auf Register Application (Anwendung registrieren).
Nach erfolgreicher Ausführung 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 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.
- Wenn die API die Basisautorisierung verwendet, prüfen Sie, ob der Header
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.
Ersetzen Sie alle Instanzen von
UrlFetchApp.fetch()
in Ihrem Code durchlogUrlFetch()
.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.