Zum Hauptinhalt springen

​
Integration mit den Search Posts-Endpunkten

Diese Seite enthält Informationen zu mehreren Tools und wichtigen Konzepten, die Sie kennen sollten, wenn Sie die Endpunkte für die jüngste Suche oder die vollständige Archivsuche in Ihr System integrieren. Wir haben die Seite in die folgenden Abschnitte unterteilt:

​
Nützliche Tools

Bevor wir einige zentrale Konzepte erkunden, empfehlen wir, eines der folgenden Tools oder Codebeispiele zu nutzen, um mit dem Testen der Funktionalität dieser Endpunkte zu beginnen.

​
Codebeispiele

Möchten Sie diese Endpunkte mit Code in Ihrer bevorzugten Programmiersprache einrichten? Auf unserer GitHub-Seite finden Sie mehrere Codebeispiele als Ausgangspunkt, darunter einen Python-Client und einen Ruby-Client.

​
Bibliotheken

Nutzen Sie eine unserer vielen Community-Bibliotheken von Drittanbietern, um den Einstieg zu erleichtern. Eine mit den v2-Endpunkten kompatible Bibliothek finden Sie, indem Sie nach dem entsprechenden Versions-Tag suchen.

​
Postman

Postman ist ein hervorragendes Tool, mit dem Sie diese Endpunkte testen können. Jede Postman-Anfrage enthält sämtliche Parameter des jeweiligen Endpunkts, damit Sie schnell verstehen, welche Optionen Ihnen zur Verfügung stehen. Weitere Informationen zu unseren Postman-Collections finden Sie auf der Seite Postman verwenden.  

​
Wichtige Konzepte

​
Authentifizierung

Alle X API v2-Endpunkte erfordern, dass Sie Ihre Anfragen mit einem Satz von Zugangsdaten authentifizieren, auch bekannt als Schlüssel und Token. Sie können entweder OAuth 1.0a User Context, OAuth 2.0 App-Only oder OAuth 2.0 Authorization Code with PKCE verwenden, um Ihre Anfragen an den Endpunkt für die jüngste Suche zu authentifizieren. Beim Endpunkt für die Vollarchiv-Suche müssen Sie OAuth 2.0 App-Only verwenden. OAuth 2.0 App-Only erfordert lediglich, dass Sie einen OAuth 2.0 App Access Token mit Ihrer Anfrage übermitteln. Sie können entweder einen App Access Token direkt in einer Developer-App generieren oder einen mithilfe des Endpunkts POST oauth2/token erzeugen. OAuth 1.0a User Context erfordert die Verwendung Ihrer API-Schlüssel, Benutzer-Zugriffstoken und einiger weiterer Parameter, um einen Authorization-Header zu erstellen, den Sie anschließend mit Ihrer Anfrage übermitteln. Die Zugriffstoken müssen dem Benutzer zugeordnet sein, in dessen Namen Sie die Anfrage stellen. Wenn Sie einen Satz Zugriffstoken für einen anderen Benutzer generieren möchten, muss dieser Ihre App mittels des 3-stufigen OAuth-Flows autorisieren. Bitte beachten Sie, dass OAuth 1.0a schwierig anzuwenden sein kann. Wenn Sie mit dieser Authentifizierungsmethode nicht vertraut sind, empfehlen wir, eine Bibliothek zu verwenden, ein Tool wie Postman zu nutzen oder OAuth 2.0 zur Authentifizierung Ihrer Anfragen zu verwenden. Wenn Sie einen Post oder private Metriken von diesen Endpunkten anfordern möchten, müssen Sie entweder OAuth 1.0a User Context oder OAuth 2.0 Authorization Code with PKCE verwenden, was sicherstellt, dass Sie die entsprechenden Berechtigungen des Benutzers besitzen, dem dieser Inhalt gehört. OAuth 2.0 Authorization Code with PKCE ermöglicht eine feinere Kontrolle über den Umfang (Scope) einer Anwendung sowie Autorisierungsabläufe über mehrere Geräte hinweg. OAuth 2.0 ermöglicht es Ihnen, spezifische, fein granulare Scopes auszuwählen, die Ihnen bestimmte Berechtigungen im Namen eines Benutzers geben. Um OAuth 2.0 in Ihrer App zu aktivieren, müssen Sie es in den Authentifizierungseinstellungen Ihrer App aktivieren, die im Abschnitt App-Einstellungen des Entwicklerportals zu finden sind.
Bitte beachtenWenn Sie die folgenden Felder anfordern, ist OAuth 1.0a User Context oder OAuth 2.0 Authorization Code erforderlich:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics

​

Entwicklerportal, Projekte und Developer-Apps Um mit Endpunkten der X API v2 zu arbeiten, müssen Sie sich zunächst für ein Entwicklerkonto registrieren, in diesem Konto ein Projekt einrichten und in diesem Projekt eine Developer-App erstellen. Die in dieser Developer-App generierten Schlüssel und Token funktionieren für diese Suchendpunkte. Sie können Schlüssel und Token aus einem Projekt mit jedem Zugriffslevel verwenden, um Anfragen an den Endpunkt für die jüngste Suche zu stellen. Für Anfragen an den Endpunkt für die Suche im vollständigen Archiv benötigen Sie jedoch ein Projekt mit dem Zugriffslevel Pro oder Enterprise. Wenn Sie Enterprise-Zugriff haben, steht Ihnen zusätzliche Funktionalität zur Verfügung, einschließlich weiterer Operatoren und längerer Abfragen.  

​
Ratenlimits

Jeden Tag senden viele Tausend Entwickler Anfragen an die X API. Um das Volumen zu steuern, werden für jeden Endpunkt Ratenlimits festgelegt, die die Anzahl der Anfragen begrenzen, die ein Entwickler im Namen einer App oder eines authentifizierten Nutzers stellen kann. Für diese Endpunkte gelten je nach verwendeter Authentifizierungsmethode unterschiedliche Ratenlimits. Die Ratenlimits auf App-Ebene gelten für eine App, die Anfragen mit OAuth 2.0 App-Only stellt, während das Ratenlimit auf Nutzer-Ebene für Anfragen gilt, die im Namen des autorisierenden Nutzers mit OAuth 1.0a User Context oder OAuth 2.0 Authorization Code with PKCE gestellt werden. Diese beiden Ratenlimits basieren auf der Häufigkeit von Anfragen innerhalb eines 15‑Minuten‑Fensters. Beispielsweise kann eine App, die OAuth 2.0 App-Only verwendet, um Anfragen an den Endpunkt für die jüngste Suche zu stellen, 450 Anfragen (einschließlich Paginierungsanfragen) innerhalb eines 15‑Minuten‑Zeitraums ausführen. Dieselbe App kann im gleichen 15‑Minuten‑Zeitraum und mit zwei verschiedenen authentifizierten Nutzern (mit OAuth 1.0a User Context oder OAuth 2.0 Authorization Code with PKCE) bis zu 180 Anfragen (einschließlich Paginierungsanfragen) an den Endpunkt für die jüngste Suche pro authentifiziertem Nutzer stellen.  

​
Felder und Erweiterungen

Die X API v2 ermöglicht es Ihnen, mit Felder und Erweiterungen genau festzulegen, welche Daten Sie von der API zurückerhalten möchten. Der Parameter expansions ermöglicht es, im Payload referenzierte Objekte aufzulösen. Beispielsweise erlaubt dieser Endpunkt, mithilfe des Parameters expansions Umfrage-, Orts-, Medien- und andere Objekte anzufordern. Die Parameter für Felder ermöglichen es Ihnen, präzise zu bestimmen, welche Felder innerhalb der verschiedenen Datenobjekte Sie erhalten möchten. Standardmäßig enthalten die primären Post-Objekte, die von diesen Endpunkten zurückgegeben werden, die Felder id und text (zusätzlich zu edit_history_tweet_ids für Beiträge, die nach der Einführung dieser Funktion erstellt wurden). Um zusätzliche Felder wie author_id oder public_metrics zu erhalten, müssen Sie diese ausdrücklich über die Felder-Parameter anfordern. Einige wichtige Felder, die Sie für Ihre Integration in Betracht ziehen sollten, sind unsere Umfragedaten, Metriken, Post-Anmerkungen und die Felder zur Konversations-ID. Wir haben unserem X API v2 Data Dictionary eine Anleitung hinzugefügt, wie Sie Felder und Erweiterungen gemeinsam verwenden.  

​
Metriken

Die X API v2-Endpunkte ermöglichen es Ihnen, Metriken direkt aus den zurückgegebenen Objekten abzurufen, sofern Sie die entsprechenden Felder in Ihrer Anfrage angeben. Es gibt einige Einschränkungen bei Beitragsmetriken, die Sie kennen sollten, insbesondere im Hinblick auf den Datenschutz der Nutzenden und die folgenden Antwortfelder:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Die genannten Felder enthalten private Metrikdaten. Das bedeutet: Um diese Daten im Namen der Autorin bzw. des Autors eines Beitrags über den Endpunkt für die jüngste Suche abzurufen, müssen Sie von dieser Person autorisiert sein und OAuth 1.0a User Context verwenden. Da diese Authentifizierungsmethode nur mit der jüngsten Suche genutzt werden kann, lassen sich diese Metriken nicht über den Endpunkt für die Vollarchivsuche abrufen. Um beispielsweise non_public_metrics für Beiträge der Benutzer-ID 1234 zu erhalten, müssen Sie Zugriffstoken einbeziehen, die diesem Nutzenden zugeordnet sind. Sie können Nutzende Ihre App autorisieren lassen und mithilfe des 3-stufigen OAuth-Flows einen Satz zugeordneter Zugriffstoken erhalten. Alle non_public_metrics, organic_metrics und promoted_metrics sind nur für Beiträge verfügbar, die in den letzten 30 Tagen erstellt wurden. Das bedeutet, dass bei Anforderung der genannten Felder die Ergebnisse automatisch so gefiltert werden, dass nur Beiträge aus den letzten 30 Tagen enthalten sind. Wenn diese Felder angefordert werden, werden nur Beiträge zurückgegeben, die vom authentifizierten Nutzenden verfasst wurden; für alle anderen Beiträge wird eine Fehlermeldung ausgegeben.  

​
Erstellen von Suchanfragen

Das zentrale Merkmal dieser Endpunkte ist die Verwendung einer einzelnen Suchanfrage, um die Posts zu filtern, die an Sie ausgeliefert werden. Diese Anfragen bestehen aus Operatoren, die auf Post- und Nutzerattributen matchen, etwa auf Stichwörtern im Text, Hashtags und URLs. Operatoren können mithilfe boolescher Logik und Klammern zu Anfragen kombiniert werden, um das Matching-Verhalten der Anfrage zu verfeinern. Weitere Informationen finden Sie in unserem Leitfaden zum Erstellen einer Abfrage. Diese Endpunkte nutzen Paginierung, damit Antworten schnell bereitgestellt werden. Wenn es mehr Ergebnisse gibt, als in einer einzelnen Antwort gesendet werden können (bis zu 100 Posts für die jüngste Suche und 500 für die Vollarchivsuche), müssen Sie paginieren. Verwenden Sie den Parameter max_results, um festzulegen, wie viele Ergebnisse pro Seite zurückgegeben werden, und den Parameter pagination_token, um die nächste Ergebnisseite abzurufen. Weitere Informationen finden Sie in unserem Leitfaden zur Paginierung.

​
Beitragsobergrenzen

Die Search-Posts-Endpunkte sind in der Anzahl der Beiträge begrenzt, die sie in einem bestimmten Monat zurückgeben können, unabhängig von der Paginierung. Unabhängig davon, welchen Such-Endpunkt Sie verwenden, werden die zurückgegebenen Beiträge auf die projektweite Beitragsobergrenze angerechnet. Die Nutzung wird im Entwicklerportal angezeigt, und der „Monat“ beginnt an dem Tag Ihrer Abonnementverlängerung, der auf dem Entwicklerportal-Dashboard angezeigt wird. Beitragsbearbeitungen Beiträge, die für Bearbeitungen berechtigt sind, können bis zu fünfmal innerhalb von 30 Minuten nach Veröffentlichung des ursprünglichen Beitrags bearbeitet werden. Die Such-Endpunkte liefern stets die neueste Version des Beitrags. Wenn Sie nur Beiträge anfordern, die vor 30 oder mehr Minuten veröffentlicht wurden, erhalten Sie immer die endgültige Version des Beitrags. Wenn Sie jedoch einen nahezu in Echtzeit liegenden Anwendungsfall haben und Beiträge abfragen, die innerhalb der letzten 30 Minuten veröffentlicht wurden, könnten diese Beiträge nach dem Empfang durch Sie bearbeitet worden sein. Diese Beiträge können über die Suche oder den Post-Lookup-Endpunkt erneut hydriert werden, um ihren endgültigen Status zu bestätigen. Weitere Informationen zur Funktionsweise von Beitragsbearbeitungen finden Sie auf der Seite Grundlagen zu Beitragsbearbeitungen.   Nächste Schritte Senden Sie Ihre erste Anfrage an einen Search-Posts-Endpunkt Sehen Sie eine vollständige Liste von Parametern, Feldern und mehr in unseren API-Referenzseiten Holen Sie sich Support oder beheben Sie einen Fehler