Consultar dados de registro usando a estrutura da GraphQL API

Crie uma GraphQL API personalizada para consultar dados de registro de um componente ou sistema de terceiros.

Por exemplo, você pode criar um componente que exibe os casos associados a um SLA. Você pode usar o Next Experience UI Framework para desenvolver o componente necessário e acessar dados de caso da plataforma criando um esquema GraphQL que define os dados na tabela Caso.

Para saber mais sobre como desenvolver componentes, consulte Desenvolvimento de componentes para Workspace.

Benefícios do GraphQL

GraphQL é uma linguagem de consulta da web otimizada para desenvolvimento do lado do cliente. Usando o GraphQL com script, você pode:

• Descubra campos e objetos disponíveis para consulta por meio de introspecção.
• Consulte os dados exatos necessários de um componente.
• Gerencie várias consultas possíveis de uma única API, em oposição a vários endpoints para uma solicitação REST.
• Integre a sistemas de terceiros tornando o esquema público.
• Gere a consulta GraphQL do seu componente e processe a resposta.

O que saber antes de começar

Antes de começar a criar GraphQL APIs personalizadas, certifique-se de ter:

• Conhecimento da GraphQL para criar um esquema.
• Conhecimento de JavaScript para definir o comportamento da API.
• Conhecimento geral de conceitos de componentes da Web.
• Um componente Espaço personalizado para consumir dados de registro.
• Noções básicas sobre o modelo de dados ServiceNow que você deseja expor no esquema.
• Conhecimento de GlideRecord para mapear campos para registrar dados em seus scripts de resolvedor.

Visão geral da GraphQL

Criar uma GraphQL API com script inclui estas partes:

Linguagem de definição de esquema GraphQL (SDL)

Defina a estrutura e o tipo de dados dos campos disponíveis em uma consulta GraphQL. Você pode definir o SDL usando o campo Script de esquema na tabela Esquemas de script GraphQL [sys_graphql_schema]. O SDL oferece suporte somente a operações de consulta e mutação.

Resolvedores

Defina os dados retornados por cada campo. Você pode definir os resolvedores de cada campo na lista relacionada Resolvedores de script da GraphQL no formulário Esquemas de script da GraphQL.

Resolvedores de tipos

Resolva interfaces e uniões em tipos GraphQL concretos. Por exemplo, você pode definir uma união entre um tipo de incidente e um tipo de problema. Use o script typeresolver para definir quando retornar qual. Você pode definir os resolvedores de tipo na lista relacionada Resolvedores de tipo de script da GraphQL no formulário Esquemas de script da GraphQL.

Mapeamentos do resolvedor

Mapeie resolvedores para campos no esquema. Você pode definir mapeamentos de resolvedor na lista relacionada Mapeamentos de resolvedor de script da GraphQL no formulário Esquemas de script da GraphQL.

Para saber mais sobre a linguagem de consulta GraphQL, consulte o site da GraphQL.

Para testar consultas às suas GraphQL APIs, você pode usar o GraphQL Explorer, uma ferramenta de teste GraphQL integrada. Para obter mais informações, consulte Testar GraphQL APIs com o GraphQL Explorer.

Limitações

Os seguintes recursos do GraphQL não são compatíveis:

• Operações de assinatura
• Tipos escalares personalizados

Introspecção

Por padrão, as consultas introspectivas em seus esquemas personalizados não estão habilitadas. Para ativar a introspecção, consulte Habilitar consultas introspectivas para esquemas GraphQL.

Namespaces

As APIs GraphQL têm dois namespaces diferentes:

Namespace da aplicação

O namespace da aplicação personalizada. Para saber mais sobre namespaces da aplicação, consulte Escopo da aplicação.

Namespace do esquema

O namespace do esquema para garantir que todas as consultas sejam exclusivas. Você pode ter vários namespaces de esquema em uma única aplicação.

Ao consultar dados, você deve incluir os dois namespaces na consulta. Por exemplo, a consulta a seguir está procurando dados com os seguintes namespaces:

• Namespace da aplicação: x_graph_scope
• Namespace do esquema: planeta

query {
  x_graph_scope {
    planet {
      findAll {
        name
        mass
        distance
      }
    }
  }
}

Diretivas e funções globais

Diretiva de esquema@source

Mapeia um campo GraphQL para o valor de uma propriedade do objeto primário. Se o campo tiver um script de resolvedor separado, o sistema usará o registro para o qual ele resolve em vez do objeto primário.

Use a diretiva @source no seu script de esquema.

Diretiva de consulta@defer

Adie o processamento de um fragmento GraphQL para mais tarde na consulta. Use esta diretiva de consulta para atrasar o retorno de dados para campos de resposta lenta em um fragmento. Transmita os resultados do campo do fragmento adiado como uma resposta de várias partes.

Nota:

Para usar a diretiva @defer, seu cliente GraphQL deve aceitar cabeçalhos HTTP de várias partes/mistos. Por exemplo, defina os cabeçalhos HTTP como Aceitar: multiparte/misto; limite = "-".

Use a diretiva @defer para melhorar o tempo de interação do usuário. Evite aplicar esta diretiva de consulta indiscriminadamente, pois ela também pode causar degradações no desempenho. Realize testes de desempenho para determinar quais campos podem ser adiados para melhor desempenho.

Funções de resolvedor

Essas funções estão disponíveis no objeto env global.

• getArguments(): retorna os argumentos do campo anterior.
• getSource(): retorna o objeto primário.

Use no seu script de resolvedor.

Funções de TypeResolver

Essas funções estão disponíveis no objeto env global.

• getArguments(): retorna os argumentos do campo anterior.
• getObject(): retorna o objeto primário.
• getTypeName(): retorna o nome da interface ou do tipo de união.

Use no seu script typeresolver.

Aplicação de demonstração

Para ver um esquema de calendário PTO do GraphQL de demonstração com mutações e consultas, habilite o plug-in GraphQL Framework Demo Application (com.glide.graphql.framework.demo).

• Criar um esquema GraphQL
  Crie um esquema GraphQL para disponibilizar dados para consultas GraphQL.
• Habilitar consultas introspectivas para esquemas GraphQL
  Descubra as consultas e mutações compatíveis com os esquemas em sua instância, habilitando a introspecção.
• Testar GraphQL APIs com o GraphQL Explorer
  Teste a consulta de suas GraphQL APIs usando uma ferramenta de teste GraphQL integrada.
• Consultar um esquema GraphQL de um componente
  Acesse os dados de registro em um componente consultando seu esquema GraphQL com script.
• Propriedades do sistema GraphQL
  Configure o comportamento da estrutura da GraphQL API. Por exemplo, você pode configurar se deseja permitir consultas introspectivas em seu esquema.