Skip to main content
Die GraphQL-API stellt eine unterstützte Teilmenge der REST-Funktionen von Ayrshare über einen einzigen Endpunkt bereit. Jedes bereitgestellte Feld ruft denselben zugrunde liegenden Controller auf wie sein REST-Gegenstück, sodass Authentifizierung, Berechtigungen, Kontingente und Antwortdaten dem REST-Verhalten folgen. REST bleibt die umfassendere API; im Schema oder im Explorer sehen Sie genau, welche Operationen GraphQL unterstützt. Neu hinzu kommt die Möglichkeit, in einer Anfrage nach mehreren Dingen zu fragen und die aktuell unterstützte GraphQL-Oberfläche direkt aus dem Schema zu erkunden, ohne die Dokumentation Seite für Seite zu lesen. Das Schema beschreibt jedes unterstützte Anfragefeld und die typisierten Auswahlen, die bei strukturierten Antworten verfügbar sind; Operationen, die den REST-Envelope als JSON zurückgeben, erhalten diese vollständige Nutzlast.
Senden Sie einen POST mit einem JSON-Body, der eine query enthält, genau wie bei jedem GraphQL-Endpunkt. GET und DELETE geben 405 Method Not Allowed zurück – Abfragen über GET sind in der GraphQL-Spezifikation optional und werden hier nicht unterstützt.

​
Ihre erste Abfrage

Die Antwort ist derselbe JSON-Envelope, den der REST-History-Endpunkt zurückgibt, eingebettet in das data-Feld von GraphQL:

​
Mehrere Dinge auf einmal abfragen

Der Grund, zu GraphQL zu greifen, ist eine Anfrage wie diese, die vier REST-Aufrufe erfordern würde:
Ein einziger Roundtrip liefert alle vier. Beachten Sie, dass es sich um vier Root-Operationsfelder und vier API-Aufrufe für die Abrechnung handelt, nicht um einen. Die Auswahl verschachtelter Antwortfelder verursacht keine zusätzlichen Aufrufe – siehe Limits und Abrechnung.

​
Authentifizierung

Identisch zu REST. Senden Sie Ihren API Key als Bearer-Token:
Wenn Ihr Konto User Profiles verwendet, können Operationen, die profileKey bereitstellen, ein Profil auf zwei Arten auswählen:
  • Senden Sie Profile-Key als anfrageweiten Standardwert.
  • Übergeben Sie profileKey an einem einzelnen Feld, um diesen Standardwert zu überschreiben, sodass eine Anfrage auf mehr als ein Profil wirken kann.
Sind beide vorhanden, hat das Feldargument Vorrang. Felder auf Kontoebene oder nur für das Primärkonto stellen profileKey nicht bereit und können einen Profile-Key-Header ablehnen; createProfile muss beispielsweise den primären API Key ohne diesen Header verwenden. Prüfen Sie den Geltungsbereich in der Schemadefinition jedes Felds, und unter Mehrere Benutzer verwalten erfahren Sie, wie Profile Keys funktionieren.

​
Ausprobieren, ohne Code zu schreiben

Der GraphQL Explorer ist ein interaktiver Browser für das aktuelle Schema. Er listet jede verfügbare GraphQL-Operation mit ihren Argumenten und Beschreibungen auf, vervollständigt Ihre Eingaben automatisch und führt Abfragen gegen Ihr Konto aus. Zum Durchsuchen des Schemas benötigen Sie keinen API Key – das Schema ist öffentlich, genau wie diese Dokumentation. Um eine Abfrage auszuführen, benötigen Sie jedoch einen, da jede Operation dieselbe Authentifizierung wie REST durchläuft.

​
Sollten Sie GraphQL oder REST verwenden?

REST bleibt die primäre Schnittstelle, um die herum der Großteil unserer Dokumentation, SDKs und Integrationen aufgebaut ist. Greifen Sie zu GraphQL, wenn:
  • Sie mehrere voneinander unabhängige Daten benötigen und diese in einem Roundtrip erhalten möchten.
  • Sie maschinenlesbare Operationsnamen, Argumente, Eingabeobjekte, Enums und typisierte Antwortauswahlen wünschen. Die meisten Antworten bleiben JSON, damit der vollständige REST-Envelope erhalten bleibt; createPost gibt derzeit ein typisiertes PostResult zurück.
  • Sie die API erkunden und sehen möchten, was es gibt, ohne zwischen Dokumentationsseiten zu wechseln.
Bleiben Sie bei REST, wenn:
  • Sie Dateien hochladen. Medien-Bytes können nicht über eine GraphQL-Anfrage übertragen werden – den unterstützten Weg finden Sie unter Medien hochladen.
  • Sie eines unserer SDKs oder No-Code-Integrationen verwenden, die REST sprechen.
  • Sie möglichst wenige Abhängigkeiten wünschen. Ein REST-Aufruf benötigt nichts außer einem HTTP-Client.
Beide Schnittstellen werden parallel unterstützt, und Sie können sie in derselben Integration frei kombinieren.
  • Die API verwenden – Operationen finden, Argumenttypen und Medien hochladen.
  • Fehler – welche Fehler den HTTP-Status ändern, warum fehlgeschlagene Operationen dennoch HTTP 200 zurückgeben und wie Sie mit Teilerfolgen umgehen.
  • Limits und Abrechnung – Obergrenzen für die Abfragegröße und wie Anfragen gezählt werden.