Escopo, Global

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 7 min. de leitura

    • . Opcional A API interage com um único registro retornado pelo GlideQuery , Fluxo ou GlideRecord APIs, mesmo quando não existem. Grave scripts que têm menos probabilidade de resultar em erro ao lidar com resultados de consulta nulos ou indefinidos.

    Você pode obter um Opcional objeto destas maneiras:

    Esses métodos são estáticos e não exigem uma instância da classe:

    Você pode usar esses métodos estáticos com qualquer API que retorne um único valor, como GlideRecord .

    Use Opcional API em scripts do lado do servidor com escopo ou globais. Esta API requer o plug-in GlideQuery [com.sn_glidequery].

    Implementação

    Esta API pode funcionar com GlideQuery e. Fluxo APIs em um padrão do construtor em que o método chama a cadeia, cada método criado no resultado retornado do método anterior. Use métodos para definir os atributos da consulta. Os métodos não são executados até que você chame um método de terminal, um método que retorna um resultado de consulta, permitindo que você defina os requisitos da consulta antes de executá-la.

    Se a consulta retornar um único registro, o sistema encapsulará o resultado em um objeto Opcional. Se a consulta retornar um fluxo de registros, o sistema encapsulará o resultado em um objeto Fluxo. Esses objetos permitem gerenciar o resultado usando um conjunto de métodos em cada API.

    Por exemplo, isso O script executa uma consulta na tabela Tarefa, agrupa os registros por prioridade e retorna cada prioridade que tem reatribuições totais maiores que quatro. 

    var query = new global.GlideQuery('task')
    .where('active', true) //Returns new GlideQuery object with a "where" clause.
    .groupBy('priority') //Returns new GlideQuery object with a "group by" clause.
    .aggregate('sum', 'reassignment_count') //Returns new GlideQuery object with a "sum(reassignment_count)" clause.
    .having('sum', 'reassignment_count', '>', 4) //Returns new GlideQuery object with a "having reassignment_count > 4" clause.
    .select() //Returns a stream of records wrapped in a Stream object.  
    .forEach(function (priority){ //Terminal method in the Stream class that executes the query and returns the result. 
      gs.info("Priority " + priority.group.priority + ": " + priority.sum.reassignment_count + " reassignments");
    });
    Saída:
    Priority 1: 11 reassignments
Priority 3: 6 reassignments
Priority 5: 5 reassignments

    Métodos de terminal

    Por motivos de desempenho, uma consulta busca dados somente quando você chama um método de terminal. Estes são os métodos de terminal do Opcional classe:

    Vazio (motivo da cadeia de caracteres)

    Retorna um objeto opcional vazio. Use este método em uma cláusula else para lidar com uma consulta que pode não retornar um resultado.

    Nota:
    Este método é estático. Você não precisa de uma instância da classe para usar este método.
    Tabela 1. Parâmetros
    Nome Tipo Descrição
    motivo Cadeia de caracteres Opcional. Motivo exibido no log quando Opcional.get() É chamado no objeto Opcional vazio.
    Tabela 2. Retornos
    Tipo Descrição
    Opcional Objeto usado para interagir com um único registro.

    Este exemplo mostra como gerar um objeto Opcional vazio quando uma consulta não retorna um resultado.

    var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

    Saída:

    NiceError: [2020-08-26T23:23:37.402Z]: get() called on empty Optional: no results

    Filtro (predicado de função)

    Aplica uma função de predicado, uma função que usa um único valor e retorna verdadeiro ou falso, ao registro dentro do objeto Opcional. Se a função retornar verdadeiro, o método retornará o registro opcional inalterado. Se a função retornar falso, retornará um objeto Opcional vazio.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    predicado Função Função de predicado a ser aplicada ao valor dentro do objeto Opcional. Deve retornar um valor booliano.
    Tabela 4. Retornos
    Tipo Descrição
    Opcional Objeto usado para interagir com um único registro.

    Este exemplo mostra como aplicar uma função de filtro a um resultado opcional.

    var filteredQuery = new global.GlideQuery('sys_user')
    .getBy({ sys_id: 'f682abf03710200044e0bfc8bcbe5d38' }, ['phone'])
    .filter(function (user) {
        return phoneRegex.test(user.phone);
    });

    Opcional - flatMap(function fn)

    Aplica uma função que retorna um objeto Opcional ao resultado de uma consulta. Use este método para executar uma segunda consulta usando o resultado da primeira.

    Tabela 5. Parâmetros
    Nome Tipo Descrição
    fn Função Função a ser aplicada Para os resultados da consulta que retornou o objeto Opcional.
    Tabela 6. Retornos
    Tipo Descrição
    Opcional Objeto usado para interagir com um único registro.

    Este exemplo mostra como executar uma consulta da tabela Usuário com base no resultado de uma consulta anterior.

    new global.GlideQuery('alm_asset')
    .whereNotNull('owned_by')
    .selectOne('owned_by')
    .flatMap(function (asset) {
        return new global.GlideQuery('sys_user')
            .getBy({ sys_id: asset.owned_by }, ['first_name', 'last_name', 'company.name'])
    })
    .ifPresent(GQ.jsonDebug);

    Saída:

    {
  "sys_id": "46d59205a9fe198101d603f5de37bfa3",
  "first_name": "John",
  "last_name": "Bohnhamn",
  "company": {
    "name": "ACME North America"
  }
}

    Opcional - get()

    Retorna o registro dentro do objeto Opcional ou gera um erro se a consulta não retornar um registro.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 8. Retorna
    Tipo Descrição
    Qualquer O registro dentro do objeto Opcional. Se o valor for nulo ou indefinido, o sistema lançará um erro.

    Este exemplo mostra como obter o valor de um único registro.

    var value = new global.GlideQuery('sys_user')
    .selectOne('first_name') //Returns the result of the query inside an Optional object
    .get(); //Calls Optional.get() on the Optional object

gs.info(JSON.stringify(value));

    Saída:

    {
   "first_name":"fred",
   "sys_id":"005d500b536073005e0addeeff7b12f4"
}

    Opcional - ifPresent(function fn)

    Aplica uma função ao registro em um objeto opcional. Se o objeto Opcional não contiver um registro, a função não será executada.

    Tabela 9. Parâmetros
    Nome Tipo Descrição
    fn Função A função a ser aplicada ao registro no objeto Opcional.
    Tabela 10. Retornos
    Tipo Descrição
    Nenhum(a)

    Este exemplo mostra como imprimir um valor, se ele existir.

    var user = new global.GlideQuery('sys_user')
    .where('sys_id', 'f682abf03710200044e0bfc8bcbe5d38')
    .selectOne('zip')
    .ifPresent(function (user) {
      gs.info('Zip Code: ' + user.zip);
    });

    Opcional - isEmpty()

    Retorna verdadeiro se o objeto Opcional estiver vazio.

    Tabela 11. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 12. Retorna
    Tipo Descrição
    Booliano

    Sinalizador que indica se o resultado de uma consulta contém um valor.

    Valores válidos:
    • Verdadeiro: A consulta retorna nulo ou indefinido.
    • Falso: A consulta retorna um valor.

    Este exemplo mostra como verificar se o resultado de uma consulta está vazio.

    var checkEmpty = new global.GlideQuery('sys_user')
    .where('last_name', 'Barker')
    .selectOne()
    .isEmpty();

gs.info(checkEmpty);

    Saída:

    true

    Opcional - isPresent()

    Verifica se um objeto Opcional contém um valor.

    Tabela 13. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 14. Retorna
    Tipo Descrição
    Booliano

    Sinalizador que indica se o resultado de uma consulta contém um valor.

    Valores válidos:
    • Verdadeiro: A consulta retorna um valor.
    • Falso: A consulta retorna nulo ou indefinido.

    Este exemplo mostra como verificar se uma consulta retorna um resultado.

    var checkPresent = new global.GlideQuery('sys_user')    
   .where('last_name', 'Luddy')
   .selectOne('first_name')
   .isPresent();

gs.info(checkPresent);

    Saída:

    true

    Opcional - lazy(function lazyGetFn)

    Retorna um novo objeto Opcional. Em vez de conter o registro, o objeto contém uma função para obter o registro que só é chamado se e quando solicitado no código.

    Use este método para atrasar a obtenção do valor até que ele seja necessário. Você pode fazer isso se solicitar o valor de uma fonte lenta e não quiser tornar seu código desnecessariamente lento. Caso contrário, você pode retornar um objeto opcional usando GlideQuery e. Fluxo APIs.

    Nota:
    Este método é estático. Você não precisa de uma instância da classe para usar este método.
    Tabela 15. Parâmetros
    Nome Tipo Descrição
    GetFn Função Função que retorna um único registro como resultado de uma consulta. Por exemplo: 
    var userGr = new GlideRecord('sys_user');
    Tabela 16. Retornos
    Tipo Descrição
    Opcional Objeto que contém o resultado da consulta no formato Optional<result> .

    Este exemplo mostra como obter um objeto Opcional com base em uma consulta GlideRecord.

    var userOptional = global.Optional.lazy(function () {
    var userGr = new GlideRecord('sys_user');
    userGr.setLimit(1);
    userGr.query();
    return userGr.next() ? userGr.getUniqueValue() : null;
});

gs.info(userOptional);

    Saída:

    Optional<005d500b536073005e0addeeff7b12f4>

    MAP(function fn)

    Aplica uma função ao resultado de uma consulta.

    Tabela 17. Parâmetros
    Nome Tipo Descrição
    fn Função Função a ser aplicada ao resultado da consulta.
    Tabela 18. Retornos
    Tipo Descrição
    Opcional Objeto que contém os resultados da consulta atualizada pela função no formato Optional<result> .

    Este exemplo mostra como aplicar uma função que transforma um valor em maiúsculas ao resultado de uma consulta.

    var value = new global.GlideQuery('sys_user')
    .whereNotNull('first_name')
    .selectOne('first_name')
    .map(function (user) {
	       return user.first_name.toUpperCase();
    });

gs.info(value);

    Saída:

    Optional<ABEL>

    Opcional - de (qualquer valor)

    Quebra um determinado valor em um objeto Opcional. Por exemplo, você pode encapsular o resultado de uma consulta GlideRecord em um objeto Opcional para usar os métodos associados.

    Nota:
    Este método é estático. Você não precisa de uma instância da classe para usar este método.
    Tabela 19. Parâmetros
    Nome Tipo Descrição
    valor Qualquer Valor dentro do objeto Opcional.
    Tabela 20. Retornos
    Tipo Descrição
    Opcional Objeto que contém o valor passado no formato Optional<value> .

    Este exemplo mostra como gerar um objeto opcional com base em uma consulta GlideRecord.

    var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

    Saída:

    00c269162d761010f87708b56757cbb3

    Opcional - ouElse (qualquer valor padrão)

    Adiciona um valor padrão ao objeto Opcional se a consulta não retornar resultados.

    Tabela 21. Parâmetros
    Nome Tipo Descrição
    defaultValue Qualquer Valor no objeto Opcional se a consulta não retornar resultados.
    Tabela 22. Retornos
    Tipo Descrição
    Qualquer Valor no objeto Opcional se a consulta não retornar resultados.

    Este exemplo mostra como retornar um valor, mesmo quando a consulta está incorreta.

    var user = new global.GlideQuery('sys_user')
    .get('1234', ['first_name', 'last_name'])
    .orElse({ first_name: 'Default', last_name: 'User' });

gs.info(JSON.stringify(user))

    Saída:

    {
   "first_name":"Default",
   "last_name":"User"
}