Skip to main content

​
Eine Operation finden

Das Schema ist maßgeblich für die unterstützte GraphQL-Teilmenge: Operations-Roots, Namen, Argumente, Eingabetypen und Enum-Werte. Beschreibungen liefern Hinweise zur Verwendung, und der GraphQL Explorer zeigt beides an. Für Funktionen, die nur über REST verfügbar sind, verwenden Sie die REST-API-Referenz. Operationsnamen orientieren sich an den REST-Endpunkten, die sie ansprechen, in camelCase. GET /history ist postHistory, GET /analytics/social ist socialAnalytics, POST /post ist createPost.

​
Queries lesen, Mutations schreiben

Queries sind Lese- und Validierungsvorgänge, die auf unserer Seite nichts ändern. Mutations veröffentlichen oder ändern einen Zustand, starten Vorgänge oder versenden E-Mails. Weder das REST-HTTP-Verb noch die Kosten eines Aufrufs bestimmen den Root:
  • validatePost prüft einen Beitrag, ohne ihn zu veröffentlichen.
  • validateMedia prüft, ob eine Medien-URL erreichbar ist.
  • generatePost ist eine Query, weil sich auf unserer Seite nichts ändert. Sie zählt dennoch als API-Aufruf und gibt jedes Mal einen anderen Text zurück. Stellen Sie daher sicher, dass ein Client-Cache oder ein automatisches erneutes Abrufen sie nicht unbemerkt wiederholt.
  • mediaUploadUrl ist eine Mutation, weil sie eine Upload-URL für Ihr Konto erstellt.
  • linkAnalytics ist eine Mutation, weil sie einen per E-Mail versendeten Bericht anfordern kann.
  • userBatch ist eine Mutation, weil sie einen Exportauftrag startet.
Verwenden Sie den Explorer oder das Schema, um den Root jeder unterstützten Operation zu bestätigen.

​
Einen Beitrag erstellen

createPost nimmt ein einziges input-Argument entgegen, sodass der gesamte Beitrag ein Objekt ist:
Die Eingabe spiegelt den dokumentierten REST-Post-Endpunkt wider, einschließlich der netzwerkspezifischen Optionsobjekte und der REST-Formen, die mehr als eine JSON-Struktur akzeptieren:
Ein Beitrag kann in einem Netzwerk erfolgreich sein und in einem anderen fehlschlagen. Das ist kein Fehlschlag der Anfrage – siehe Fehler.

​
Argumenttypen

Die meisten Argumente sind gewöhnliche Strings, Zahlen und Booleans. Drei Fälle sollten Sie kennen.

​
Enums

Viele String-Argumente mit einer abgeschlossenen unterstützten Wertemenge sind GraphQL-Enums und werden ohne Anführungszeichen und in Großbuchstaben geschrieben:
Nicht "instagram". Der Server ordnet jedes akzeptierte Enum genau dem Wert zu, den der zugrunde liegende REST-Controller erwartet – oft, aber nicht immer, ein String in Kleinbuchstaben. Ein ungültiges Enum wird bei der GraphQL-Validierung abgelehnt, bevor die Operation ausgeführt wird, sodass Sie ein Tippfehler nichts kostet. Manche Argumente tragen in verschiedenen Operationen denselben Namen, akzeptieren aber unterschiedliche Werte, weil sich die Endpunkte tatsächlich unterscheiden. reviews(platform:) akzeptiert nur GMB und FACEBOOK, da dies die einzigen Netzwerke mit Bewertungen sind. Die Autovervollständigung Ihres Clients zeigt für jede Operation die richtige Wertemenge an.

​
Der JSON-Skalar

Einige Argumente sind als JSON statt als bestimmter Typ typisiert. Das ist dort der Fall, wo ein Wert berechtigterweise mehr als eine Struktur hat und kein einzelner GraphQL-Typ ihn zutreffend beschreiben könnte:
  • explainError(code:) akzeptiert 215 oder “215”, weil Kunden Fehlercodes in beiden Formen vorliegen haben.
  • createPost(input:) verwendet JSON für Felder wie post und mediaUrls, die gemeinsame Werte oder plattformspezifische Objekte sein können.
  • createAutomation(triggers:, actions:) nehmen Arrays entgegen, deren Felder vom type des jeweiligen Eintrags abhängen.
  • boostFacebookPost(interests:) akzeptiert Meta-Interessen-IDs als Strings oder Zahlen.
Übergeben Sie denselben Wert, den Sie im entsprechenden REST-Body senden würden. Ein JSON-Argument ist kein Schlupfloch: Der Resolver validiert es vor der Weiterleitung, sodass ein ungültiger Wert einen Validierungsfehler zurückgibt und keinen API-Aufruf verbraucht.

​
Optionale Argumente und Nullwerte

Bei optionalen Argumenten und optionalen Feldern innerhalb von Eingabeobjekten wird ein explizites null so behandelt, als wäre der Wert weggelassen worden. Null-Elemente innerhalb von Listen bleiben erhalten, wenn der Listentyp sie zulässt.

​
Antworten lesen

Die meisten Operationen geben einen JSON-Skalar zurück, der den vollständigen REST-Antwort-Envelope enthält. Wählen Sie daher das Root-Feld ohne Unterfelder aus. createPost gibt derzeit ein typisiertes PostResult zurück, wählen Sie also dessen Felder aus:
Typisierte Antworttypen wie PostResult enthalten außerdem raw: JSON! mit der vollständigen, unveränderten REST-Antwort:
raw ist dauerhaft vorhanden und sorgt dafür, dass ein neues Feld in der REST-Antwort über GraphQL niemals unerreichbar ist, während wir seine Typisierung nachziehen. Wenn Sie etwas benötigen, das die typisierten Felder nicht bereitstellen, fragen Sie raw ab.

​
Medien hochladen

Medien-Bytes können nicht über eine GraphQL-Anfrage übertragen werden. Eine GraphQL-Anfrage ist ein einzelnes JSON-Dokument mit einem Limit von 64 KB. Es gibt also kein Feld, das eine Datei akzeptiert, und ein als base64 in der Query kodiertes Bild würde dieses Limit bei allem, was größer als ein Thumbnail ist, überschreiten. Der unterstützte Weg umgeht das Problem vollständig und ist ohnehin schneller als ein Upload über eine API, da Ihre Bytes direkt in den Speicher gehen:
  1. Fordern Sie eine Upload-URL an:
  2. Lesen Sie data.mediaUploadUrl.uploadUrl, accessUrl und contentType aus dem zurückgegebenen JSON.
  3. Senden Sie Ihre Datei per PUT direkt an uploadUrl, nicht an die Ayrshare-API, und setzen Sie den Content-Type-Header der Anfrage auf den zurückgegebenen contentType.
  4. Übergeben Sie nach erfolgreichem Upload accessUrl in createPost.input.mediaUrls:
Behandeln Sie uploadUrl als kurzlebige Schreibberechtigung und protokollieren oder veröffentlichen Sie sie nicht. accessUrl ist die Medien-URL, die beim Erstellen des Beitrags verwendet wird. Sie können auch weiterhin die REST-Upload-Endpunkte verwenden und die resultierenden URLs aus GraphQL referenzieren. Beide Schnittstellen teilen sich dieselbe Medienbibliothek.
  • Fehler – HTTP-Statuscodes, Fehlerstrukturen und Teilerfolge.
  • Limits und Abrechnung – Obergrenzen für die Abfragegröße und wie Anfragen gezählt werden.