---
sourceDocument: Referência de API do Xanadu
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - pt-BR

ft:publication_title :

    - Referência de API do Xanadu

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Opcional - com escopo, global

# Opcional - com escopo, global {#ariaid-title1}

* Versão de lançamento: Xanadu
* 
* Atualizado 1 de ago. de 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 7 min. de leitura

A API opcional interage com um único registro retornado pelas APIs GlideQuery, Streamou GlideRecord, mesmo quando ele não existe. Escreva scripts com menor probabilidade de resultar em erro ao lidar com resultados de consulta nulos ou indefinidos.

Você pode obter um objeto opcional destas maneiras:  
* Retorne um objeto opcional desses métodos na classe GlideQuery. Para obter mais informações, consulte [GlideQuery](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GlideQueryGlobalAPI "A inclusão de script GlideQuery é uma alternativa à API GlideRecord para executar operações CRUD em dados de registro de scripts do lado do servidor.").
  * [getBy ()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-getBy_O_O "Retorna um objeto opcional que contém um único registro com base em um conjunto de pares de nome-valor para consulta. Assume o operador '=' para cada par de nome-valor.")
  * [obter ()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-get_S_O "Retorna um único registro da consulta.")
  * [insert()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-insert_O_O "Insere um registro e retorna um objeto opcional que contém o registro.")
  * [inserirOuAtualizar()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-insertOrUpdate_O_O "Atualiza um registro existente ou insere um novo registro, caso ainda não exista.")
  * [atualizar ()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-update_O_O "Atualiza um registro existente que corresponde às condições definidas.")
  * [selecionarUm()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-selectOne_S "Retorna o resultado da consulta como um objeto opcional que contém os campos especificados.")
  * [média ()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-avg_S "Retorna a média agregada de um determinado campo numérico.")
  * [máx. ()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-max_S "Retorna o máximo agregado de um determinado campo.")
  * [mín ()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-min_S "Retorna o mínimo agregado de um determinado campo.")
  * [soma ()](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GQ-sum_S "Retorna a soma agregada de um determinado campo numérico.")
  {#OptionalGlobalAPI__ul_bgr_bhl_4mb}
* Retorne um objeto opcional do método [find()](https://servicenow-prod.fluidtopics.net/fzIJduEXjC~UEIBxIRy~9g#Stream-find_F "Retorna o primeiro registro ou item no objeto de fluxo que corresponde à função de predicado. Se nenhuma função de predicado for fornecida, o método retornará o primeiro registro ou item no fluxo.") na classe Stream. Para obter mais informações sobre o Stream, consulte a API [Stream](https://servicenow-prod.fluidtopics.net/fzIJduEXjC~UEIBxIRy~9g#StreamGlobalAPI "A API Stream fornece métodos para interagir com um fluxo de itens, como registros. Por exemplo, você pode usar o método forEach() para atualizar o estado de cada registro em um fluxo retornado pela API GlideQuery.").
* Use o método [preguiçoso ()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-lazy_F "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.") para gerar o valor do Opcional, se necessário.
{#OptionalGlobalAPI__ul_d3q_3dl_4mb}

Esses métodos são estáticos e não requerem uma instância da classe:  
* [preguiçoso ()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-lazy_F "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.")
* [de ()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-of_A "Encapsula 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.")
* [vazio ()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-empty_S "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.")
{#OptionalGlobalAPI__ul_jpq_2px_5mb}

Você pode usar esses métodos estáticos com qualquer API que retorne um único valor, como [GlideRecord](https://servicenow-prod.fluidtopics.net/FBR_zQLvGAsgQtw7~4MAGA#c_GlideRecordScopedAPI "A API GlideRecord com escopo é usada para operações de banco de dados.").

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

## Implementação {#OptionalGlobalAPI__section_wqk_wwv_wmb}

Esta API pode funcionar com as APIs [GlideQuery](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GlideQueryGlobalAPI "A inclusão de script GlideQuery é uma alternativa à API GlideRecord para executar operações CRUD em dados de registro de scripts do lado do servidor.") e [Stream](https://servicenow-prod.fluidtopics.net/fzIJduEXjC~UEIBxIRy~9g#StreamGlobalAPI "A API Stream fornece métodos para interagir com um fluxo de itens, como registros. Por exemplo, você pode usar o método forEach() para atualizar o estado de cada registro em um fluxo retornado pela API GlideQuery.") em um padrão de construtor em que o método chama a cadeia, cada método se baseia 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 agrupará o resultado em um objeto opcional. Se a consulta retornar um fluxo de registros, o sistema agrupará o resultado em um objeto Stream. Esses objetos permitem gerenciar o resultado usando um conjunto de métodos em cada API.

Por exemplo, este script executa uma consulta na Tabela de tarefas, agrupa os registros por prioridade e retorna cada prioridade que tem um total de reatribuições maior que quatro.{#OptionalGlobalAPI__code-ex-desc}  

    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 {#OptionalGlobalAPI__section_dcn_52g_ymb}

Por motivos de desempenho, uma consulta só busca dados quando você chama um método de terminal. Estes são os métodos de terminal da classe Opcional :  
* [obter ()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-get "Retorna o registro dentro do objeto opcional ou gera um erro se a consulta não retornar um registro.")
* [ouElse()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-orElse "Adiciona um valor padrão no objeto opcional se a consulta não retornar nenhum resultado.")
* [ifPresent()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-ifPresent_F "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.")
* [estáVazio()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-isEmpty "Retorna verdadeiro se o objeto opcional estiver vazio.")
* [estáPresente()](https://servicenow-prod.fluidtopics.net/7SFmnBHO5B_AA3dUMbI7mA#Optional-isPresent "Verifica se um objeto opcional contém um valor.")
{#OptionalGlobalAPI__ul_z2v_tgg_ymb}

## Opcional - vazio (motivo da cadeia de caracteres) {#ariaid-title2}

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.
{#Optional-empty_S__table_xj5_k1l_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| motivo | Cadeia de caracteres | Opcional. Motivo exibido no log quando Opcional.get() é chamado no objeto opcional vazio. |
[Tabela 1. Parâmetros]

{#Optional-empty_S__table_xj5_k1l_4mb} {#Optional-empty_S__table_yj5_k1l_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Opcional | Objeto usado para interagir com um único registro. |
[Tabela 2. Retorna]

{#Optional-empty_S__table_yj5_k1l_4mb}  
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

## Opcional - filter (predicado da função) {#ariaid-title3}

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, ela retornará um objeto opcional vazio.
{#Optional-filter_F__table_qyn_g1l_4mb__entry__3}

| 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 3. Parâmetros]

{#Optional-filter_F__table_qyn_g1l_4mb} {#Optional-filter_F__table_ryn_g1l_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Opcional | Objeto usado para interagir com um único registro. |
[Tabela 4. Retorna]

{#Optional-filter_F__table_ryn_g1l_4mb}  
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 - planaMap(Função fn) {#ariaid-title4}

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.
{#Optional-flatMap_F__table_nrd_tgf_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| fn | Função | Função para aplicar aos resultados da consulta que retornou o objeto opcional. |
[Tabela 5. Parâmetros]

{#Optional-flatMap_F__table_nrd_tgf_4mb} {#Optional-flatMap_F__table_ord_tgf_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Opcional | Objeto usado para interagir com um único registro. |
[Tabela 6. Retorna]

{#Optional-flatMap_F__table_ord_tgf_4mb}  
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() {#ariaid-title5}

Retorna o registro dentro do objeto opcional ou gera um erro se a consulta não retornar um registro.
{#Optional-get__table_px4_5gf_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| Nenhum |   |   |
[Tabela 7. Parâmetros]

{#Optional-get__table_px4_5gf_4mb} {#Optional-get__table_qx4_5gf_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Qualquer | O registro dentro do objeto opcional. Se o valor for nulo ou indefinido, o sistema emitirá um erro. |
[Tabela 8. Retorna]

{#Optional-get__table_qx4_5gf_4mb}  
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) {#ariaid-title6}

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.
{#Optional-ifPresent_F__table_n55_21l_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| fn | Função | A função a ser aplicada ao registro no objeto opcional. |
[Tabela 9. Parâmetros]

{#Optional-ifPresent_F__table_n55_21l_4mb} {#Optional-ifPresent_F__table_o55_21l_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Nenhum(a) |   |
[Tabela 10. Retorna]

{#Optional-ifPresent_F__table_o55_21l_4mb}  
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() {#ariaid-title7}

Retorna verdadeiro se o objeto opcional estiver vazio.
{#Optional-isEmpty__table_yhd_b1l_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| Nenhum |   |   |
[Tabela 11. Parâmetros]

{#Optional-isEmpty__table_yhd_b1l_4mb} {#Optional-isEmpty__table_zhd_b1l_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Booliano | Sinalizador que indica se o resultado de uma consulta contém um valor. Valores válidos: * verdadeiro: a consulta retorna nula ou indefinida. * falso: a consulta retorna um valor. {#Optional-isEmpty__ul_htd_wcs_smb} |
[Tabela 12. Retorna]

{#Optional-isEmpty__table_zhd_b1l_4mb}  
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() {#ariaid-title8}

Verifica se um objeto opcional contém um valor.
{#Optional-isPresent__table_icx_c1l_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| Nenhum |   |   |
[Tabela 13. Parâmetros]

{#Optional-isPresent__table_icx_c1l_4mb} {#Optional-isPresent__table_jcx_c1l_4mb__entry__2}

| 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 nula ou indefinida. {#Optional-isPresent__ul_htd_wcs_smb} |
[Tabela 14. Retorna]

{#Optional-isPresent__table_jcx_c1l_4mb}  
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 - preguiçoso (Função preguiçosoGetFn) {#ariaid-title9}

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 seja necessário. Você pode fazer isso se estiver solicitando o valor de uma origem lenta e não quiser tornar seu código mais lento desnecessariamente. Caso contrário, você pode retornar um objeto opcional usando as APIs [GlideQuery](https://servicenow-prod.fluidtopics.net/weOjD4QxtQmCMbvdegl_Dw#GlideQueryGlobalAPI "A inclusão de script GlideQuery é uma alternativa à API GlideRecord para executar operações CRUD em dados de registro de scripts do lado do servidor.") e [Stream](https://servicenow-prod.fluidtopics.net/fzIJduEXjC~UEIBxIRy~9g#StreamGlobalAPI "A API Stream fornece métodos para interagir com um fluxo de itens, como registros. Por exemplo, você pode usar o método forEach() para atualizar o estado de cada registro em um fluxo retornado pela API GlideQuery.").  
Nota:  
Este método é estático. Você não precisa de uma instância da classe para usar este método.
{#Optional-lazy_F__table_edm_lwj_5mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| preguiçosoGetFn | Função | Função que retorna um único registro como resultado de uma consulta. Por exemplo: var userGr = new GlideRecord('sys_user'); |
[Tabela 15. Parâmetros]

{#Optional-lazy_F__table_edm_lwj_5mb} {#Optional-lazy_F__table_fdm_lwj_5mb__entry__2}

| Tipo | Descrição |
|-|-|
| Opcional | Objeto que contém o resultado da consulta no formato `Opcional`\<result\> . |
[Tabela 16. Retorna]

{#Optional-lazy_F__table_fdm_lwj_5mb}  
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>

## Opcional - map(Função fn) {#ariaid-title10}

Aplica uma função ao resultado de uma consulta.
{#Optional-map_F__table_zkh_rgf_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| fn | Função | Função a ser aplicada ao resultado da consulta. |
[Tabela 17. Parâmetros]

{#Optional-map_F__table_zkh_rgf_4mb} {#Optional-map_F__table_alh_rgf_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Opcional | Objeto que contém os resultados da consulta atualizados pela função no formato `Opcional`\<result\> . |
[Tabela 18. Retorna]

{#Optional-map_F__table_alh_rgf_4mb}  
Este exemplo mostra como aplicar uma função que transforma um valor em maiúsculas no 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) {#ariaid-title11}

Encapsula 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.
{#Optional-of_A__table_yhw_n1l_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| valor | Qualquer | Valor dentro do objeto opcional. |
[Tabela 19. Parâmetros]

{#Optional-of_A__table_yhw_n1l_4mb} {#Optional-of_A__table_zhw_n1l_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Opcional | Objeto que contém o valor passado no formato `Opcional`\<value\> . |
[Tabela 20. Retorna]

{#Optional-of_A__table_zhw_n1l_4mb}  
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 - orElse(Any defaultValue) {#ariaid-title12}

Adiciona um valor padrão no objeto opcional se a consulta não retornar nenhum resultado.
{#Optional-orElse__table_wl3_zzk_4mb__entry__3}

| Nome | Tipo | Descrição |
|-|-|-|
| defaultValue | Qualquer | Valor dentro do objeto opcional se a consulta não retornar nenhum resultado. |
[Tabela 21. Parâmetros]

{#Optional-orElse__table_wl3_zzk_4mb} {#Optional-orElse__table_xl3_zzk_4mb__entry__2}

| Tipo | Descrição |
|-|-|
| Qualquer | Valor dentro do objeto opcional se a consulta não retornar nenhum resultado. |
[Tabela 22. Retorna]

{#Optional-orElse__table_xl3_zzk_4mb}  
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"
    }