Consultar dados de registro usando a estrutura da GraphQL API
Crie uma GraphQL API personalizada para consultar dados de registro de um componente ou de um sistema de terceiros.
Por exemplo, você pode criar um componente que exibe os casos associados a um ANS. Você pode usar o Estrutura de IU do Next Experience para desenvolver o componente necessário e acessar dados de caso da plataforma criando um esquema GraphQL que define dados na tabela Caso.
Para saber mais sobre como desenvolver componentes, consulte Desenvolvimento de componentes para o espaço.
Benefícios da GraphQL
GraphQL é uma linguagem de consulta na 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 de que você precisa de um componente.
- Gerencie várias consultas possíveis de uma única API, em vez de vários endpoints para uma solicitação REST.
- Integre com sistemas de terceiros tornando o esquema público.
- Gere a consulta GraphQL a partir 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 GraphQL para criar um esquema.
- Conhecimento 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.
- Compreensão do modelo de dados ServiceNow que você deseja expor no esquema.
- Conhecimento GlideRecord para mapear campos para registrar dados em seus scripts de resolução.
Visão geral da GraphQL
A criação de uma GraphQL API com script inclui estas partes:
- GraphQL Schema Definition Language (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 GraphQL Scripted Schemas [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 para cada campo na lista relacionada Resolvedores de script da GraphQL no formulário Esquemas de script da GraphQL.
- Resolvedores de tipo
- Resolva interfaces e uniões em tipos GraphQL concretos. Por exemplo, você pode definir um sindicato entre um tipo de
incidentee um tipode problema. Use o script typeresolver para definir quando retornar qual. Você pode definir os typeresolvers na lista relacionada GraphQL Scripted Typeresolvers no formulário GraphQL Scripted Schemas. - Mapeamentos de resolvedor
- Mapeie resolvedores para campos no esquema. Você pode definir mapeamentos de resolvedor na lista relacionada Mapeamentos de resolvedores com script GraphQL no formulário Esquemas com script GraphQL.
Para saber mais sobre a linguagem de consulta GraphQL, consulte o site da GraphQL.
Para testar consultas às suas APIs GraphQL, você pode usar o GraphQL Explorer, uma ferramenta de teste GraphQL integrada. Para obter mais informações, consulte Testar APIs da GraphQL com o Explorador da GraphQL.
Limitações
Os seguintes recursos 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 de aplicações, 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 ambos os namespaces em sua consulta. Por exemplo, a consulta a seguir está pesquisando 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 é resolvido em vez do objeto primário.
Use a diretiva
@sourceno script do 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. Transmitir os resultados de 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 multipartes/mistos. Por exemplo, defina os cabeçalhos HTTP comoAceitar: multipart/misto; limite="-".Use a diretiva
@deferpara 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 um 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 em 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 tipo de união.
Use em seu script typeresolver.
Aplicação de demonstração
Para ver um esquema de calendário GraphQL PTO de demonstração com mutação e consultas, habilite o plug-in GraphQL Framework Demo Application (com.glide.graphql.framework.demo).