Skip to main content

​
Encontrar una operación

El esquema es la referencia autorizada para el subconjunto GraphQL compatible: raíces de operación, nombres, argumentos, tipos de entrada y valores de enum. Las descripciones ofrecen orientación de uso, y el GraphQL Explorer muestra ambos. Para las capacidades exclusivas de REST, usa la referencia de la API REST. Los nombres de las operaciones siguen los endpoints REST a los que llegan, en camelCase. GET /history es postHistory, GET /analytics/social es socialAnalytics, POST /post es createPost.

​
Las queries leen, las mutations escriben

Las queries son lecturas y validaciones que no cambian nada en nuestro lado. Las mutations publican o cambian el estado, inician trabajos o envían emails. Ni el verbo HTTP de REST ni el coste de una llamada deciden la raíz:
  • validatePost comprueba una publicación sin publicarla.
  • validateMedia comprueba que una URL de medios sea accesible.
  • generatePost es una query porque no cambia nada en nuestro lado. Aun así cuenta como una llamada a la API y devuelve un texto distinto cada vez, así que asegúrate de que una caché del cliente o una recarga automática no la repita sin que te des cuenta.
  • mediaUploadUrl es una mutation porque crea una URL de subida para tu cuenta.
  • linkAnalytics es una mutation porque puede solicitar un informe por email.
  • userBatch es una mutation porque inicia un trabajo de exportación.
Usa el Explorer o el esquema para confirmar la raíz de cada operación compatible.

​
Crear una publicación

createPost recibe un único argumento input, así que toda la publicación es un solo objeto:
La entrada refleja el endpoint REST de publicación documentado, incluidos los objetos de opciones por red y las formas REST que aceptan más de una estructura JSON:
Una publicación puede tener éxito en una red y fallar en otra. Eso no es un fallo de la solicitud; consulta Errores.

​
Tipos de argumentos

La mayoría de los argumentos son cadenas, números y booleanos corrientes. Hay tres casos que conviene conocer.

​
Enums

Muchos argumentos de tipo cadena con un conjunto cerrado de valores compatibles son enums de GraphQL, que se escriben sin comillas y en mayúsculas:
No "instagram". El servidor asigna cada enum aceptado al valor exacto que espera el controlador REST subyacente: a menudo, aunque no siempre, una cadena en minúsculas. Un enum no válido se rechaza durante la validación de GraphQL antes de que se ejecute la operación, así que un error tipográfico no te cuesta nada. Algunos argumentos comparten nombre entre operaciones pero aceptan valores diferentes, porque los endpoints realmente son distintos. reviews(platform:) acepta solo GMB y FACEBOOK, ya que son las únicas redes con reseñas. El autocompletado de tu cliente mostrará el conjunto correcto para cada operación.

​
El escalar JSON

Algunos argumentos están tipados como JSON en lugar de un tipo específico. Esto ocurre cuando un valor tiene legítimamente más de una forma y ningún tipo GraphQL único podría describirlo con precisión:
  • explainError(code:) acepta 215 o “215”, porque los clientes guardan los códigos de error de ambas formas.
  • createPost(input:) usa JSON para campos como post y mediaUrls, que pueden ser valores compartidos u objetos por plataforma.
  • createAutomation(triggers:, actions:) reciben arrays cuyos campos dependen del type de cada entrada.
  • boostFacebookPost(interests:) acepta ids de intereses de Meta como cadenas o números.
Pasa el mismo valor que enviarías en el cuerpo REST correspondiente. Un argumento JSON no es una laguna: el resolver lo valida antes de despacharlo, así que un valor no válido devuelve un error de validación y no consume ninguna llamada a la API.

​
Argumentos opcionales y nulls

En los argumentos opcionales y en los campos opcionales dentro de objetos de entrada, un null explícito se normaliza como omisión. Los miembros null dentro de listas se conservan cuando el tipo de la lista lo permite.

​
Leer las respuestas

La mayoría de las operaciones devuelven un escalar JSON que contiene el envoltorio completo de la respuesta REST, así que selecciona el campo raíz sin subcampos. createPost devuelve actualmente un PostResult tipado, así que selecciona sus campos:
Los tipos de respuesta tipados como PostResult también incluyen raw: JSON!, que contiene la respuesta REST completa sin modificar:
raw es permanente y existe para que un campo nuevo que aparezca en la respuesta REST nunca quede inaccesible desde GraphQL mientras nos ponemos al día con su tipado. Si necesitas algo que los campos tipados no exponen, pide raw.

​
Subir medios

Los bytes de los medios no pueden viajar en una solicitud GraphQL. Una solicitud GraphQL es un único documento JSON con un límite de 64 KB, así que no hay ningún campo que acepte un archivo, y codificar una imagen en base64 dentro de la query superaría ese límite para cualquier cosa más grande que una miniatura. La vía compatible evita el problema por completo y, en cualquier caso, es más rápida que subir a través de una API, porque tus bytes van directamente al almacenamiento:
  1. Pide una URL de subida:
  2. Lee data.mediaUploadUrl.uploadUrl, accessUrl y contentType del JSON devuelto.
  3. Haz PUT de tu archivo directamente a uploadUrl, no a la API de Ayrshare, estableciendo el encabezado Content-Type de la solicitud con el contentType devuelto.
  4. Una vez que la subida se complete correctamente, pasa accessUrl en createPost.input.mediaUrls:
Trata uploadUrl como una credencial de escritura de corta duración y no la registres ni la expongas. accessUrl es la URL de medios que se usa al crear la publicación. También puedes seguir usando los endpoints REST de subida y hacer referencia a las URLs resultantes desde GraphQL. Ambas interfaces comparten la misma biblioteca de medios.
  • Errores: códigos de estado HTTP, estructura de los errores y éxito parcial.
  • Límites y facturación: límites de tamaño de las consultas y cómo se cuentan las solicitudes.