Skip to main content

​
Encontrando uma operação

O schema é a fonte oficial para o subconjunto GraphQL suportado: raízes de operação, nomes, argumentos, tipos de entrada e valores de enum. As descrições fornecem orientações de uso, e o GraphQL Explorer expõe ambos. Para recursos disponíveis apenas no REST, use a referência da REST API. Os nomes das operações seguem os endpoints REST que acessam, em camelCase. GET /history é postHistory, GET /analytics/social é socialAnalytics, POST /post é createPost.

​
Queries leem, mutations escrevem

Queries são leituras e validações que não alteram nada do nosso lado. Mutations publicam ou alteram estado, iniciam trabalhos ou enviam e-mails. Nem o verbo HTTP do REST nem o custo de uma chamada determinam a raiz:
  • validatePost verifica uma publicação sem publicá-la.
  • validateMedia verifica se uma URL de mídia está acessível.
  • generatePost é uma query porque nada muda do nosso lado. Ainda assim, ela conta como uma chamada de API e retorna um texto diferente a cada vez, então garanta que um cache do cliente ou um refetch automático não a repita sem que você perceba.
  • mediaUploadUrl é uma mutation porque cria uma URL de upload para sua conta.
  • linkAnalytics é uma mutation porque pode solicitar um relatório por e-mail.
  • userBatch é uma mutation porque inicia um trabalho de exportação.
Use o Explorer ou o schema para confirmar a raiz de cada operação suportada.

​
Criando uma publicação

createPost recebe um único argumento input, então a publicação inteira é um objeto:
O input espelha o endpoint REST de publicação documentado, incluindo os objetos de opções por rede e as formas do REST que aceitam mais de um formato JSON:
Uma publicação pode ter sucesso em uma rede e falhar em outra. Isso não é uma falha da requisição — veja Erros.

​
Tipos de argumentos

A maioria dos argumentos são strings, números e booleanos comuns. Vale a pena conhecer três casos.

​
Enums

Muitos argumentos de string com um conjunto fechado de valores suportados são enums GraphQL, escritos sem aspas e em maiúsculas:
Não "instagram". O servidor mapeia cada enum aceito para o valor exato esperado pelo controlador REST subjacente — geralmente, mas nem sempre, uma string em minúsculas. Um enum inválido é rejeitado durante a validação GraphQL, antes de a operação ser executada, então um erro de digitação não custa nada. Alguns argumentos compartilham o mesmo nome entre operações, mas aceitam valores diferentes, porque os endpoints realmente diferem. reviews(platform:) aceita apenas GMB e FACEBOOK, já que essas são as únicas redes com avaliações. O autocompletar do seu cliente mostrará o conjunto correto para cada operação.

​
O scalar JSON

Alguns argumentos são tipados como JSON em vez de um tipo específico. Isso acontece quando um valor legitimamente tem mais de um formato e nenhum tipo GraphQL único conseguiria descrevê-lo com fidelidade:
  • explainError(code:) aceita 215 ou “215”, porque os clientes armazenam códigos de erro das duas formas.
  • createPost(input:) usa JSON para campos como post e mediaUrls, que podem ser valores compartilhados ou objetos por plataforma.
  • createAutomation(triggers:, actions:) recebem arrays cujos campos dependem do type de cada entrada.
  • boostFacebookPost(interests:) aceita ids de interesses da Meta como strings ou números.
Passe o mesmo valor que você enviaria no corpo REST correspondente. Um argumento JSON não é uma brecha: o resolver o valida antes do envio, então um valor inválido retorna um erro de validação e não consome nenhuma chamada de API.

​
Argumentos opcionais e nulls

Para argumentos opcionais e campos opcionais dentro de objetos de entrada, um null explícito é normalizado como omissão. Membros nulos dentro de listas são preservados quando o tipo da lista os permite.

​
Lendo respostas

A maioria das operações retorna um scalar JSON contendo o envelope completo da resposta REST, então selecione o campo raiz sem subcampos. createPost atualmente retorna um PostResult tipado, então selecione seus campos:
Tipos de resposta tipados como PostResult também incluem raw: JSON!, contendo a resposta REST completa e sem modificações:
raw é permanente e existe para que um novo campo que apareça na resposta REST nunca fique inacessível pelo GraphQL enquanto ainda não o tipamos. Se você precisar de algo que os campos tipados não expõem, solicite raw.

​
Upload de mídia

Os bytes de mídia não podem trafegar por uma requisição GraphQL. Uma requisição GraphQL é um único documento JSON com limite de 64 KB, então não há nenhum campo que aceite um arquivo, e codificar uma imagem em base64 dentro da consulta excederia esse limite para qualquer coisa maior que uma miniatura. O caminho suportado evita o problema por completo e, de qualquer forma, é mais rápido do que fazer upload por meio de uma API, porque seus bytes vão direto para o armazenamento:
  1. Solicite uma URL de upload:
  2. Leia data.mediaUploadUrl.uploadUrl, accessUrl e contentType do JSON retornado.
  3. Faça um PUT do seu arquivo diretamente para uploadUrl, e não para a API do Ayrshare, definindo o cabeçalho Content-Type da requisição com o contentType retornado.
  4. Depois que o upload for concluído, passe accessUrl em createPost.input.mediaUrls:
Trate uploadUrl como uma credencial de escrita de curta duração e não a registre em logs nem a exponha. accessUrl é a URL de mídia usada ao criar a publicação. Você também pode continuar usando os endpoints REST de upload e referenciar as URLs resultantes a partir do GraphQL. As duas interfaces compartilham a mesma biblioteca de mídia.
  • Erros — códigos de status HTTP, formatos de erro e sucesso parcial.
  • Limites e cobrança — limites de tamanho de consulta e como as requisições são contabilizadas.