Utiliser l'API GraphQL

Trouver une opération

Le schéma fait foi pour le sous-ensemble GraphQL pris en charge : racines des opérations, noms, arguments, types d’entrée et valeurs d’enum. Les descriptions fournissent des conseils d’utilisation, et le GraphQL Explorer expose les deux. Pour les fonctionnalités disponibles uniquement en REST, utilisez la référence de l’API REST. Les noms d’opérations suivent les points de terminaison REST qu’ils atteignent, en camelCase. GET /history correspond à postHistory, GET /analytics/social à socialAnalytics, POST /post à createPost.

Les queries lisent, les mutations écrivent

Les queries sont des lectures et des validations qui ne modifient rien de notre côté. Les mutations publient ou modifient un état, lancent un traitement ou envoient un e-mail. Ni le verbe HTTP REST ni le coût d’un appel ne déterminent la racine :

validatePost vérifie une publication sans la publier.
validateMedia vérifie qu’une URL de média est accessible.
generatePost est une query car rien ne change de notre côté. Elle compte tout de même comme un appel API et renvoie un texte différent à chaque fois ; assurez-vous donc qu’un cache client ou un refetch automatique ne la répète pas à votre insu.
mediaUploadUrl est une mutation car elle crée une URL de téléversement pour votre compte.
linkAnalytics est une mutation car elle peut demander un rapport envoyé par e-mail.
userBatch est une mutation car elle lance une tâche d’export.

Utilisez l’Explorer ou le schéma pour confirmer la racine de chaque opération prise en charge.

Créer une publication

createPost prend un seul argument input, de sorte que la publication entière est un seul objet :

mutation {
  createPost(input: {
    post: "Hello from GraphQL"
    platforms: [LINKEDIN]
    idempotencyKey: "post-2026-09-01-001"
  }) {
    status
    id
  }
}

L’entrée reproduit le point de terminaison REST de publication documenté, y compris les objets d’options par réseau et les formes REST qui acceptent plusieurs structures JSON :

mutation {
  createPost(input: {
    post: "New video"
    platforms: [YOUTUBE]
    mediaUrls: ["https://example.com/video.mp4"]
    idempotencyKey: "youtube-video-001"
    youTubeOptions: {
      title: "My video"
      visibility: PUBLIC
    }
  }) {
    status
    id
    postIds { platform postUrl }
  }
}

Une publication peut réussir sur un réseau et échouer sur un autre. Il ne s’agit pas d’un échec de la requête : consultez Erreurs.

Types d’arguments

La plupart des arguments sont des chaînes, des nombres et des booléens ordinaires. Trois cas méritent d’être connus.

Enums

De nombreux arguments de type chaîne dont l’ensemble de valeurs prises en charge est fermé sont des enums GraphQL, écrits sans guillemets et en majuscules :

{ socialAnalytics(platforms: [INSTAGRAM, TIKTOK]) }

Et non "instagram". Le serveur associe chaque enum accepté à la valeur exacte attendue par le contrôleur REST sous-jacent, souvent (mais pas toujours) une chaîne en minuscules. Un enum invalide est rejeté lors de la validation GraphQL avant l’exécution de l’opération ; une faute de frappe ne vous coûte donc rien. Certains arguments partagent un nom entre plusieurs opérations mais acceptent des valeurs différentes, car les points de terminaison diffèrent réellement. reviews(platform:) n’accepte que GMB et FACEBOOK, car ce sont les seuls réseaux proposant des avis. L’autocomplétion de votre client affichera l’ensemble correct pour chaque opération.

Le scalaire JSON

Quelques arguments sont typés JSON plutôt qu’avec un type spécifique. C’est le cas lorsqu’une valeur peut légitimement avoir plusieurs structures et qu’aucun type GraphQL unique ne pourrait la décrire fidèlement :

explainError(code:) accepte 215 ou “215”, car les clients conservent les codes d’erreur sous les deux formes.
createPost(input:) utilise JSON pour des champs tels que post et mediaUrls, qui peuvent être des valeurs partagées ou des objets par plateforme.
createAutomation(triggers:, actions:) prennent des tableaux dont les champs dépendent du type de chaque entrée.
boostFacebookPost(interests:) accepte les identifiants de centres d’intérêt Meta sous forme de chaînes ou de nombres.

Transmettez la même valeur que celle que vous enverriez dans le corps REST correspondant. Un argument JSON n’est pas une échappatoire : le resolver le valide avant l’envoi, de sorte qu’une valeur invalide renvoie une erreur de validation et ne consomme aucun appel API.

Arguments facultatifs et valeurs null

Pour les arguments facultatifs et les champs facultatifs des objets d’entrée, un null explicite est traité comme une omission. Les éléments null au sein des listes sont conservés lorsque le type de liste les autorise.

Lire les réponses

La plupart des opérations renvoient un scalaire JSON contenant l’enveloppe de réponse REST complète ; sélectionnez donc le champ racine sans sous-champs. createPost renvoie actuellement un PostResult typé ; sélectionnez donc ses champs :

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    id
    postIds { platform postUrl }
    errors { platform message code }
  }
}

Les types de réponse typés tels que PostResult incluent également raw: JSON!, qui contient la réponse REST complète et non modifiée :

mutation {
  createPost(input: {
    post: "Hi"
    platforms: [LINKEDIN]
    idempotencyKey: "linkedin-hi-001"
  }) {
    status
    raw
  }
}

raw est permanent et existe pour qu’un nouveau champ apparaissant dans la réponse REST ne soit jamais inaccessible depuis GraphQL pendant que nous rattrapons son typage. Si vous avez besoin de quelque chose que les champs typés n’exposent pas, demandez raw.

Téléverser des médias

Les octets des médias ne peuvent pas transiter par une requête GraphQL. Une requête GraphQL est un document JSON unique soumis à une limite de 64 Ko ; il n’existe donc aucun champ acceptant un fichier, et encoder une image en base64 dans la query dépasserait cette limite pour tout ce qui est plus grand qu’une miniature. La méthode prise en charge évite entièrement le problème, et elle est de toute façon plus rapide qu’un téléversement via une API, car vos octets vont directement vers le stockage :

Demandez une URL de téléversement :

mutation { mediaUploadUrl(contentType: "image/jpeg") }

Lisez data.mediaUploadUrl.uploadUrl, accessUrl et contentType dans le JSON renvoyé.
Envoyez votre fichier via PUT directement vers uploadUrl, et non vers l’API Ayrshare, en définissant l’en-tête Content-Type de la requête sur le contentType renvoyé.

Une fois le téléversement réussi, transmettez accessUrl dans createPost.input.mediaUrls :

mutation {
  createPost(input: {
    post: "With a photo"
    platforms: [INSTAGRAM]
    mediaUrls: ["https://the-returned-access-url"]
    idempotencyKey: "instagram-photo-001"
  }) {
    status
    postIds { platform postUrl }
  }
}

Traitez uploadUrl comme un identifiant d’écriture à courte durée de vie et ne le journalisez ni ne l’exposez. accessUrl est l’URL du média utilisée lors de la création de la publication. Vous pouvez aussi continuer à utiliser les points de terminaison REST de téléversement et référencer les URL obtenues depuis GraphQL. Les deux interfaces partagent la même médiathèque.

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Trouver une opération

Les queries lisent, les mutations écrivent

Créer une publication

Types d’arguments

Enums

Le scalaire JSON

Arguments facultatifs et valeurs null

Lire les réponses

Téléverser des médias

À lire ensuite

​Trouver une opération

​Les queries lisent, les mutations écrivent

​Créer une publication

​Types d’arguments

​Enums

​Le scalaire JSON

​Arguments facultatifs et valeurs null

​Lire les réponses

​Téléverser des médias

​À lire ensuite

Trouver une opération

Les queries lisent, les mutations écrivent

Créer une publication

Types d’arguments

Enums

Le scalaire JSON

Arguments facultatifs et valeurs null

Lire les réponses

Téléverser des médias

À lire ensuite