Authentifizierte Anfragen

Für den Zugriff auf die X Ads API endpoints muss Ihre Anwendung authentifizierte Webanfragen über TLS sicher an https://ads-api.x.com senden.

Die folgenden Abschnitte geben einen Überblick darüber, wie Sie authentifizierte API-Anfragen stellen, Twurl für die Interaktion mit der API einrichten und Ihre Anwendung um die Unterstützung von OAuth 1.0a erweitern, um Anfragen für Ihr Ads-Konto zu stellen.

​

Anforderungen

Bevor Sie authentifizierte Anfragen an die X Ads API stellen, benötigen Sie:

• ein genehmigtes Developer-Konto
• eine App, die für den Zugriff auf die X Ads API genehmigt wurde
• API Key und Secret, erhalten über die App-Verwaltungsoberfläche, und
• Access Tokens für einen Nutzer mit Zugriff auf ein X Ads-Konto

​

Verwendung der API

Auf die Ads API wird über https://ads-api.x.com zugegriffen. Die Standard‑REST‑API und die Ads API können mit derselben Client‑App gemeinsam genutzt werden. Die Ads API erzwingt HTTPS; daher führen Zugriffe auf ein endpoint per HTTP zu einer Fehlermeldung.

Die Ads API gibt JSON aus. Alle Bezeichner sind Strings und alle Strings sind UTF‑8. Die Ads API ist versioniert und die Version wird als erstes Pfadsegment jeder Ressourcen‑URL angegeben.

https://ads-api.x.com/<version>/accounts

​

HTTP-Verben und typische Antwortcodes

In der Ads API werden vier HTTP-Verben verwendet:

• GET ruft data ab
• POST erstellt neue data, etwa Kampagnen
• PUT aktualisiert bestehende data, z. B. Line Items
• DELETE entfernt data.

Obwohl Löschungen dauerhaft sind, können gelöschte data in den meisten GET-basierten Methoden weiterhin angezeigt werden, indem beim Anfordern der Ressource explizit der Parameter with_deleted=true angegeben wird. Andernfalls geben gelöschte Datensätze einen HTTP 404 zurück.

Eine erfolgreiche Anfrage gibt eine HTTP-200er-Antwort zurück, zusammen mit der JSON-Antwort, die beim Erstellen, Löschen oder Aktualisieren einer Ressource das Objekt repräsentiert.

Beim Aktualisieren von data mit HTTP PUT werden nur die angegebenen fields aktualisiert. Sie können einen optionalen Wert zurücksetzen, indem Sie den Parameter mit einem leeren String angeben. Dieses Parameterpaar würde beispielsweise ein bereits gesetztes end_time aufheben: &end_time=&paused=false.

Weitere Details zu Fehlerantworten finden Sie unter Error Codes & Responses.

​

Inline-Parameter

Die meisten Ressourcen-URLs enthalten einen oder mehrere Inline-Parameter. Viele URLs akzeptieren außerdem explizit deklarierte Parameter in der Query-String oder, bei POST- oder PUT-Anfragen, im Body.

Inline-Parameter werden im Abschnitt Resource Path jeder Ressource mit einem vorangestellten Doppelpunkt (”:”) gekennzeichnet. Wenn beispielsweise das Konto, an dem Sie arbeiten, die Kennung "abc1" hätte und Sie die mit einem Konto verknüpften Kampagnen abrufen würden, würden Sie über die URL https://ads-api.x.com/6/accounts/abc1/campaigns auf diese Liste zugreifen. Indem Sie den in der Ressourcen-URL (https://ads-api.x.com/6/accounts/:account_id/campaigns) beschriebenen Inline-Parameter account_id angeben, haben Sie die Anfrage auf Objekte beschränkt, die nur mit diesem Konto verknüpft sind.

​

Verwenden von Access Tokens

Die X Ads API verwendet signierte HTTPS-Anfragen, um die Identität einer Anwendung zu verifizieren und die dem Endnutzer gewährten Berechtigungen zu ermitteln, in dessen Namen die Anwendung API-Anfragen stellt, dargestellt durch das access token des Nutzers. Alle HTTP-Aufrufe an die Ads API müssen einen Authorization-Request-Header (unter Verwendung von OAuth 1.0a) über das HTTPS-Protokoll enthalten.

Sie müssen Ihre Anwendung um die Fähigkeit erweitern, OAuth 1.0a Authorization-Request-Header zu erzeugen, um sich in die X Ads API zu integrieren. Aufgrund der Komplexität signierter Anfragen empfehlen wir Partnern jedoch nachdrücklich, eine bestehende Bibliothek zu verwenden, die entweder die X API unterstützt oder die Verarbeitung von OAuth 1.0a-Anfragen implementiert – hier finden Sie eine Liste empfohlener OAuth-Bibliotheken und Authentifizierungsbeispiele.

Bitte beachten Sie, dass wir Partnern helfen können, die bei der Nutzung einer bekannten Bibliothek auf Authentifizierungsfehler stoßen, benutzerdefinierte OAuth-Implementierungen jedoch nicht unterstützen können.

​

HTTP & OAuth

Wie die X REST API v1.1 erfordert die Advertising API sowohl OAuth 1.0a als auch HTTPS. API Keys können über die App-Management-Konsole bezogen werden. Access Tokens müssen ebenfalls verwendet werden, um den „aktuellen Benutzer“ zu repräsentieren. Der aktuelle Benutzer ist ein X Konto mit Werbefunktionen.

Es wird dringend empfohlen, dass Partner eine OAuth-Bibliothek verwenden, statt eine eigene zu schreiben. Wir können beim Debuggen unterstützen, wenn eine bekannte Bibliothek verwendet wird, jedoch nicht, wenn Sie Ihre eigene OAuth-Implementierung entwickeln. Siehe die Bibliotheken, die Sie verwenden können.

Die API ist strikt in Bezug auf HTTP/1.1 und OAuth. Stellen Sie sicher, dass Sie reservierte Zeichen korrekt encodieren — sowohl in URLs als auch in POST-Bodies — bevor Sie OAuth-Signature-Base-Strings vorbereiten. Die Advertising API verwendet insbesondere „:“ bei der Angabe von Zeiten und „,“ beim Bereitstellen einer Sammlung von Optionen. Beide Zeichen gehören zu dieser reservierten Menge:

Symbol	URL-kodiert
!	%21
#	%23
$	%24
&	%26
’	%27
(	%28
)	%29
*	%2A
+	%2B
,	%2C
/	%2F
:	%3A
;	%3B
=	%3D
?	%3F
@	%40
[	%5B
]	%5D

​

Ihre erste API-Anfrage mit Twurl

X pflegt ein Befehlszeilentool, Twurl, das OAuth 1.0a-Autorisierungs-Header unterstützt und eine Alternative zu cURL darstellt. Twurl bietet eine einfache Möglichkeit, authentifizierte API-Anfragen zu stellen und die Ads API zu erkunden, bevor Sie Ihrer Anwendung eine Authentifizierung hinzufügen.

Nachdem Sie Twurl installiert und autorisiert haben, können Sie schnell access tokens generieren und authentifizierte Anfragen an die Ads API stellen.

twurl -H "ads-api.x.com" "/5/accounts/"

Nehmen Sie sich etwas Zeit, um sich mit Twurl und der API vertraut zu machen, und folgen Sie diesem Schritt-für-Schritt-Tutorial zum Erstellen einer Kampagne über die API.

​

Testen mit Postman

Für alle, die mit einem Kommandozeilen-Tool nicht vertraut sind, stellen wir auch eine Postman-Collection für die X Ads API-endpoints bereit.

Postman ist eines der beliebtesten API-Entwicklungstools in der Branche. Es ist ein HTTP-Client mit einer hervorragenden Benutzeroberfläche, der komplexe API-Anfragen erleichtert und die Produktivität steigert.

Um Postman zu installieren und die Ads API Postman-Collection zu verwenden, siehe bitte unsere Einrichtungsanleitung.

​

Erweiterung Ihrer Anwendung für authentifizierte Anfragen

Nachdem Sie sich mit dem Senden von Anfragen an die Ads API mithilfe von Twurl vertraut gemacht haben, ist es an der Zeit, Ihre Anwendung um die Erstellung von OAuth 1.0a-Authentifizierungs-Headern zu erweitern.

OAuth 1.0a-Authentifizierungs-Header enthalten Informationen, die sowohl die Identität der Anwendung als auch des Nutzers bestätigen und Manipulationen an der Anfrage verhindern. Ihre Anwendung muss für jede API-Anfrage einen neuen Authorization-Header erstellen. Viele Sprachen verfügen über Open-Source-Bibliotheken, die die Erstellung dieses Authorization-Headers für API-Anfragen an X unterstützen.

Hier finden Sie Beispiele in C#, PHP, Ruby und Python – Codebeispiele.

​

Benutzerdefinierte Implementierung

Es gibt Szenarien, in denen die OAuth 1.0a-Authentifizierung ohne die Unterstützung einer Open-Source-Bibliothek implementiert werden muss. Autorisieren einer Anfrage enthält ausführliche Anleitungen zur Implementierung der Erstellung des Authorization-Headers. Wir empfehlen nachdrücklich die Verwendung einer von der Community unterstützten Bibliothek.

Allgemeines Vorgehen:

1. Sieben Schlüssel-Wert-Paare für den Header sammeln – alle beginnend mit oauth_
2. Eine OAuth 1.0a HMAC-SHA1-Signatur mit diesen Schlüssel-Wert-Paaren erzeugen
3. Den Authorization-Header aus den obigen Werten erstellen