Criar um esquema GraphQL

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 4 min. de leitura

    • Crie um esquema GraphQL para disponibilizar dados para consultas GraphQL.

    Antes de Iniciar

    Função necessária: graphql_schema_admin ou admin

    Procedimento

    1. Navegar até Tudo > Serviços web do sistema > GraphQL > APIs GraphQL.
    2. Selecione Novo.
    3. Preencha estes campos.
      Campo Descrição
      Nome Nome do esquema.
      Namespace do esquema Deve ser exclusivo no nome da aplicação.
      Aplicação Aplicação somente leitura da qual o esquema faz parte.
      Namespace da aplicação Somente leitura. Trabalha com o namespace Esquema para evitar conflitos com esquemas com o mesmo nome.
      Ativo Opção para ativar ou desativar o esquema GraphQL.
      Esquema Definição de esquema que adere ao formato GraphQL SDL. Deve ter uma sintaxe GraphQL válida. Caso contrário, mensagens de erro serão exibidas ao salvar para indicar o problema de sintaxe.
      Nota:
      Os seguintes recursos GraphQL não são compatíveis:
      • Operações de assinatura
      • Tipos escalares personalizados

      Você pode usar esta diretiva em seu esquema:

      @origem: 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.

      Este exemplo define um tipo de objeto de incidente no esquema e usa um script de resolvedor para mapear o tipo para um GlideRecord da tabela de incidentes. O uso da diretiva @source mapeia os campos no tipo de incidente para o valor ou display_value no GlideRecord de incidente.

      type Incident {
    id: String @source(value: "sys_id.value")
    active: Boolean @source(value: "active.display_value")
    state: String @source(value: "state.display_value")    
    priority: String @source(value: "priority.display_value")
    severity: String
    description: DisplayableString
    resolvedBy: User @source(value: "resolved_by.value")
    openedBy: User @source(value: "opened_by.value")
    child_incidents: String
    opened_at: String
    resolved_at: String
    closed_at: String
    work_notes: String    
    comments: String @source(value: "comments.display_value")
    parent_incident: String
}
    4. Na seção Segurança, preencha os campos.
      Campo Descrição
      Requer autenticação Selecione esta opção para exigir autenticação para acessar o esquema. Desmarcar esta opção torna o esquema disponível publicamente.
      Requer autorização de ACL Selecione esta opção para exigir autorização de ACL da API inteira. No campo ACLs, selecione ACLs com o tipo GraphQL.

      Para usar a autorização de ACL somente para caminhos específicos, deixe esta opção desmarcada e especifique o nível para avaliar as ACLs no campo Profundidade de ACL de caminho.
      Requer SNC interno Selecione esta opção se o esquema exigir a função interna do SNC. Esta opção aparecerá somente se o plug-in Explicit Roles (com.glide.explicit_roles) estiver habilitado.
      Profundidade da ACL do caminho Especifique o nível da GraphQL API ao qual as ACLs serão aplicadas. Definir a profundidade do caminho como 3 ou menos usa menos recursos e ajuda a retornar respostas de consulta.

      Para especificar as ACLs a serem usadas para o caminho, você deve criar uma ACL com o tipo GraphQL e adicionar o caminho de API exato que começa com o namespace do esquema no campo Nome. Por exemplo: /<planet> /<findAll> /<name> . Caracteres curinga não são compatíveis. Para obter mais informações, consulte Configure an ACL rule.

      Nota:
      O campo ACLs se aplica à API inteira e é independente das ACLs aplicadas a caminhos específicos.
      ACLs Selecione ACLs com o tipo GraphQL para verificar as consultas de entrada. As ACLs selecionadas se aplicam à API inteira. Esta opção aparecerá somente se Requer autorização de ACL estiver selecionado.
      Nota:
      A API retorna mensagens de erro claras para usuários que não têm acesso a um esquema ou que não são autenticados quando a API requer autenticação para acessar.
    5. Salve o formulário.
    6. Opcional: Crie um script de resolvedor para definir qual valor o esquema retorna quando um componente consulta um campo.
      Se você não definir um resolvedor para um campo, a consulta retornará qualquer valor de campo correspondente do tipo de objeto primário. Por exemplo, suponha que você tenha um tipo de objeto Incidente em seu esquema com um campo de anotações de trabalho. O tipo de objeto Incidente tem um resolvedor que é mapeado para um GlideRecord da tabela Incidente. Se você não criar um mapeamento de resolvedor para o campo de anotações de trabalho, o sistema pesquisará a fonte de dados do objeto primário, que é o GlideRecord da tabela Incidente, para um campo de anotações de trabalho e atribuirá o valor associado.
      1. Selecione a guia Resolvedores de script da GraphQL e selecione Novo.
      2. Preencha o formulário.
        Campo Descrição
        Nome Nome do resolvedor.
        Esquema Namespace de esquema somente leitura.
        Aplicação Aplicação somente leitura da qual o esquema faz parte.
        Script Defina o valor retornado quando o campo for consultado. Funções disponíveis no objeto env global:
        • getArguments(): retorna os argumentos do campo anterior.
        • getSource(): retorna o objeto primário.

        Este script tem acesso a GlideRecord.

        Este exemplo retorna um registro da tabela Usuário quando o campo associado é consultado:

        (function process(/*ResolverEnvironment*/ env) {

    var userid = env.getArguments().id != null ? env.getArguments().id : env.getSource();
    var now_GR = new GlideRecord('sys_user');
    gr.addQuery('sys_id', userid);
    gr.queryO;
    return gr;

})(env);
      3. Selecione Enviar.
    7. Opcional: Defina os resolvedores de tipo do seu esquema para resolver interfaces e sindicatos em tipos concretos.
      1. Selecione a guia Resolvedores de tipo de script da GraphQL e selecione Novo.
      2. Preencha o formulário.
        Campo Descrição
        Esquema Namespace de esquema somente leitura.
        Tipo O tipo de interface ou união definido no esquema.
        Aplicação Aplicação somente leitura da qual o esquema faz parte.
        Script Defina o valor retornado para os tipos de união e interface. Funções 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.

        Este script tem acesso a GlideRecord.
      3. Selecione Enviar.
    8. Opcional: Mapeie o resolvedor e os registros do resolvedor de tipo para campos no esquema.
      Este mapeamento informa ao sistema qual valor retornar quando um componente consulta um campo.
      1. Selecione a guia Mapeamentos do Resolvedor de Script da GraphQL e selecione Novo.
      2. Preencha o formulário.
        Campo Descrição
        Caminho Caminho para o campo no esquema que você deseja mapear.
        Resolvedor Resolvedor a ser usado para definir os dados retornados pelo campo.
        Aplicação Aplicação somente leitura da qual o esquema faz parte.
        Esquema Namespace de esquema somente leitura.
      3. Selecione Enviar.