API de lote

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

    • . Lote A API fornece endpoints para enviar uma única solicitação que contém várias chamadas de REST API e retorna um fluxo de cargas úteis de resposta.

    Esta REST API permite que os integradores:

    • Reduza a quantidade de tempo necessário para enviar solicitações de API agrupando-as em lote e reduza a sobrecarga restringindo a autenticação, a configuração da sessão e o tráfego de ida e volta para uma única etapa.
    • Crie código mais eficiente para integrações do lado do cliente.
    • Misture formatos de item em lote e inclua-os na solicitação de lote único. Por exemplo, um lote pode incluir uma solicitação codificada em Bases64 no formato XML para enviar para um endpoint e uma solicitação codificada em Base64 no formato JSON para enviar para um endpoint diferente.
    • Receba um fluxo de cargas de resposta em troca.
    • Aplique ACLs existentes a cada chamada de API no lote.

    Você pode incluir qualquer API disponível na instância em um Lote Chamada de API. Por motivos de desempenho, evite incluir solicitações de longa execução e solicitações que recuperam grandes quantidades de dados.

    Importante:
    A API em lote tem as mesmas características de desempenho que as solicitações de API individuais, mas evita a sobrecarga de várias solicitações cliente-servidor. A API em lote não se destina ao processamento de transações paralelas e as solicitações de API de longa execução podem fazer com que a solicitação de API exceda o tempo máximo de transação e retorne uma falha.

    Limites de tamanho e processamento

    As cargas seguem estes limites de tamanho:

    • Cada item na solicitação: 5 MB​. Você pode mudar este padrão atualizando o. glide.rest.batch.max.inputSize​propriedade do sistema. Valor máximo: 10 MB.
    • Cada item na resposta: 10 MB. Você pode mudar este padrão atualizando o. glide.rest.batch.max.outputSize​propriedade do sistema ou adicionando o. X-BATCHREQUEST-MAX-OUTPUT-SIZE​cabeçalho da sua solicitação. . X-BATCHREQUEST-MAX-OUTPUT-SIZE​o valor do cabeçalho não pode exceder o valor da propriedade do sistema.
    Nota:
    Se uma solicitação for executada por mais de 30 segundos, o REST Batch API request timeouta regra de cota de transação encerra a transação. Aumentar o valor desta regra de cota de transação pode resultar em problemas de desempenho.

    Quando uma solicitação em lote atinge um tamanho ou limite de processamento, o sistema cancela a transação e retorna solicitações não processadas no sem serviço Matriz JSON na resposta.

    POST /now/batch

    Envia várias solicitações de REST API em uma única chamada.

    Você pode incluir qualquer API disponível na instância em um Lote Chamada de API. Por motivos de desempenho, evite incluir solicitações de longa execução e solicitações que recuperam grandes quantidades de dados.

    Formato de URL

    URL com controle de versão: /api/now/api_version/batch

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Versão do endpoint a ser acessado. Por exemplo, v1 ou v2 .

    Tipo de dados: Cadeia de caracteres
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Solicitar parâmetros do corpo (JSON)
    Nome Descrição
    batch_request_id ID que identifica o lote de solicitações.

    Tipo de dados: Cadeia de caracteres
    rest_requests Obrigatório. Lista de objetos de solicitação a serem incluídos na solicitação em lote.

    Tipo de dados: Matriz

    "rest_requests":[
   {
      "body": "String",
      "exclude_response_headers": Boolean,
      "headers":[Array],
      "id": "String",
      "method": "String",
      "url": "String"
   }
]
    rest_requests.body Corpo codificado em base64 da solicitação. Aplica-se somente a métodos que exigem um corpo, por exemplo, POST. Antes da codificação, o corpo pode estar em qualquer formato. Por exemplo, XML ou JSON.

    Tipo de dados: Cadeia de caracteres
    rest_requests.exclude_response_headers Sinalizador que indica se os cabeçalhos de resposta devem ser excluídos da resposta.
    Valores válidos:
    • Verdadeiro: Os cabeçalhos de resposta não estão incluídos na resposta.
    • Falso: Os cabeçalhos de resposta estão incluídos na resposta.

    Tipo de dados: Booliano

    Padrão: falso
    rest_requests.headers Lista de objetos de cabeçalho de solicitação a serem enviados para o endpoint.

    Tipo de dados: Matriz

    "headers":[
  {
    "name":"String",
    "value":"String"
  }
]
    rest_requests.headers.name Nome do cabeçalho.

    Tipo de dados: Cadeia de caracteres
    rest_requests.headers.value Valor do cabeçalho.

    Tipo de dados: Cadeia de caracteres
    rest_requests.id Obrigatório. ID de cada item no lote.

    Tipo de dados: Cadeia de caracteres
    rest_requests.method Obrigatório. Método para chamar o endpoint associado.

    Tipo de dados: Cadeia de caracteres
    rest_requests.url Obrigatório. Caminho relativo do endpoint para o qual enviar a solicitação. Inclui os parâmetros de consulta.

    Tipo de dados: Cadeia de caracteres

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou multipart/mixed.

    Para transmitir respostas de várias partes, defina glide.rest.serialize.disable_response_stream_bufferingpropriedade do sistema como verdadeira. Para obter mais informações, consulte Available system properties.
    Tipo de conteúdo Formato de dados do corpo da solicitação. Oferece suporte somente a application/json.
    X-BATCHREQUEST-MAX-OUTPUT-SIZE ​ Limite de tamanho para cada item na resposta em lote. Adicione este cabeçalho para fornecer um limite de tamanho inferior ao padrão definido pelo ​glide.rest.batch.max.outputSize​propriedade do sistema. Não é possível definir um valor maior do que o valor na propriedade do sistema.

    Padrão: 10 MB.
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da REST API .

    Tabela 6. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON)

    Nome Descrição
    batch_request_id ID do lote que corresponde a. batch_request_idparâmetro na solicitação.

    Tipo de dados: Cadeia de caracteres
    serviced_requests Lista de objetos de resposta da solicitação em lote.

    Tipo de dados: Matriz

    "serviced_requests":[
  {
    "body": "String",
    "error_message": "String",
    "execution_time": Number,
    "headers": [Array],
    "id": "String",
    "redirect_url: "String",
    "status_code": Number,
    "status_text": "String"
  }
]
    serviced_requests.body Corpo codificado em base64 da resposta. Para obter o valor do corpo, Base64 decodifica o conteúdo deste parâmetro.

    Tipo de dados: Cadeia de caracteres
    serviced_requests.error_message Se presentes, as mensagens de erro.

    Tipo de dados: Cadeia de caracteres
    serviced_requests.execution_time Tempo necessário para executar a solicitação de item em lote.

    Tipo de dados: Número

    Unidade: Milissegundos
    serviced_requests.headers Cabeçalhos do item do lote.

    Tipo de dados: Matriz

    "headers":[
  {
    "name":"String",
    "value":"String"
  }
]
    serviced_requests.headers.name Nome do cabeçalho.

    Tipo de dados: Cadeia de caracteres
    serviced_requests.headers.value Valor do cabeçalho.

    Tipo de dados: Cadeia de caracteres
    serviced_requests.id ID do item do lote que corresponde a. rest_requests.idparâmetro na solicitação.

    Tipo de dados: Cadeia de caracteres
    serviced_requests.redirect_url Se presente, o URL de redirecionamento.

    Tipo de dados: Cadeia de caracteres
    serviced_requests.status_code Código de status do item do lote.

    Tipo de dados: Número
    serviced_requests.status_text Texto do código de status do item do lote.

    Tipo de dados: Cadeia de caracteres
    unservice_requests IDs das solicitações que não foram processadas porque a solicitação em lote atingiu um tamanho ou limite de processamento.

    Tipo de dados: Matriz

    Solicitação de curl

    Esta solicitação em lote envia duas solicitações GET para a instância e uma solicitação POST para a tabela de incidentes. O corpo da solicitação POST é codificado em Base64.

    curl "https://instance.servicenow.com/api/now/v1/batch" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username":"password"\
--data "{
   \"batch_request_id\":\"1\",
   \"rest_requests\":[
      {
         \"id\":\"11\",
         \"headers\":[
            {
               \"name\":\"Content-Type\",
               \"value\":\"application/xml\"
            },
            {
               \"name\":\"Accept\",
               \"value\":\"application/xml\"
            }
         ],
         \"url\":\"/api/global/user_role_inheritance\",
         \"method\":\"GET\"
      },
      {
         \"id\":\"12\",
         \"exclude_response_headers\":true,
         \"headers\":[
            {
               \"name\":\"Content-Type\",
               \"value\":\"application/json\"
            },
            {
               \"name\":\"Accept\",
               \"value\":\"application/json\"
            }
         ],
         \"url\":\"/api/now/table/incident?sysparm_limit=1\",
         \"method\":\"GET\"
      },
      {
         \"id\":\"13\",
         \"exclude_response_headers\":true,
         \"headers\":[
            {
               \"name\":\"Content-Type\",
               \"value\":\"application/json\"
            },
            {
               \"name\":\"Accept\",
               \"value\":\"application/json\"
            }
         ],
         \"url\": \"/api/now/table/incident\",
         \"method\":\"POST\",
         \"body\": \"eyd1cmdlbmN5JzonMScsICdzaG9ydF9kZXNjcmlwdGlvbic6J015IGNvbXB1dGVyIG
          Jyb2tlJywgJ2NvbW1lbnRzJzonRWxldmF0aW5nIHVyZ2VuY3ksIHRoaXMgaXMgYSBibG9ja2luZyBpc3N1ZSd9\"
      }
   ]
}" \
    {
    "batch_request_id": "1",
    "serviced_requests": [
        {
            "id": "11",
            "body": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cmVzcG9uc2U+PHJlc3VsdD48dX
            Nlcl9uYW1lLz48L3Jlc3VsdD48L3Jlc3BvbnNlPg==",
            "status_code": 200,
            "status_text": "OK",
            "headers": [
                {
                    "name": "Pragma",
                    "value": "no-store,no-cache"
                },
                {
                    "name": "Expires",
                    "value": "0"
                },
                {
                    "name": "Content-Length",
                    "value": "88"
                },
                {
                    "name": "Content-Type",
                    "value": "application/xml; charset=UTF-8"
                },
                {
                    "name": "Cache-control",
                    "value": "no-cache,no-store,must-revalidate,max-age=-1"
                }
            ],
            "execution_time": 5
        },
        {
            "id": "12",
            "body": "eyJyZXN1bHQiOlt7InBhcmVudCI6IiIsIm1hZGVfc2xhIjoidHJ1ZSIsImNhdXNlZF9
            ieSI6IiIsIndhdGNoX2xpc3QiOiIiLCJ1cG9uX3JlamVjdCI6ImNhbmNlbCIsInN5c191cGRhdGV
            kX29uIjoiMjAxNi0xMi0xNCAwMjo0Njo0NCIsImNoaWxkX2luY2lkZW50cyI6IjAiLCJob2xkX3J
            lYXNvbiI6IiIsInRhc2tfZWZmZWN0aXZlX251bWJlciI6IklOQzAwMDAwNjAiLCJhcHByb3ZhbF9
            oaXN0b3J5IjoiIiwibnVtYmVyIjoiSU5DMDAwMDA2MCIsInJlc29sdmVkX2J5Ijp7ImxpbmsiOiJ
            odHRwczovL2s4czAwNjc5Nzgtbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGk
            vbm93L3RhYmxlL3N5c191c2VyLzUxMzcxNTNjYzYxMTIyN2MwMDBiYmQxYmQ4Y2QyMDA3IiwidmF
            sdWUiOiI1MTM3MTUzY2M2MTEyMjdjMDAwYmJkMWJkOGNkMjAwNyJ9LCJzeXNfdXBkYXRlZF9ieSI
            6ImVtcGxveWVlIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzgtbm9kZTE
            udGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2VyLzY4MWN
            jYWY5YzBhODAxNjQwMGI5OGEwNjgxOGQ1N2M3IiwidmFsdWUiOiI2ODFjY2FmOWMwYTgwMTY0MDB
            iOThhMDY4MThkNTdjNyJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiIyMDE2LTE
            yLTEyIDE1OjE5OjU3Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY3OTc4LW5
            vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXNfdXNlcl9
            ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjciLCJyb3V0ZV9yZWFzb24
            iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImVtcGxveWVlIiwia25vd2xlZGdlIjoiZmFsc2UiLCJvcmR
            lciI6IiIsImNhbGVuZGFyX3N0YyI6IjEwMjE5NyIsImNsb3NlZF9hdCI6IjIwMTYtMTItMTQgMDI",
            "status_code": 200,
            "status_text": "OK",
            "headers": [],
            "execution_time": 8
        },
        {
            "id": "13",
            "body": "eyJyZXN1bHQiOnsicGFyZW50IjoiIiwibWFkZV9zbGEiOiJ0cnVlIiwiY2F1c2VkX2J
            5IjoiIiwid2F0Y2hfbGlzdCI6IiIsInVwb25fcmVqZWN0IjoiY2FuY2VsIiwic3lzX3VwZGF0ZWR
            fb24iOiIyMDIwLTA1LTEyIDAxOjQ0OjM1IiwiY2hpbGRfaW5jaWRlbnRzIjoiMCIsImhvbGRfcmV
            hc29uIjoiIiwidGFza19lZmZlY3RpdmVfbnVtYmVyIjoiSU5DMDAxMDAwNCIsImFwcHJvdmFsX2h
            pc3RvcnkiOiIiLCJudW1iZXIiOiJJTkMwMDEwMDA0IiwicmVzb2x2ZWRfYnkiOiIiLCJzeXNfdXB
            kYXRlZF9ieSI6ImFkbWluIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzg
            tbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2V
            yLzY4MTZmNzljYzBhODAxNjQwMWM1YTMzYmUwNGJlNDQxIiwidmFsdWUiOiI2ODE2Zjc5Y2MwYTg
            wMTY0MDFjNWEzM2JlMDRiZTQ0MSJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiI
            yMDIwLTA1LTEyIDAxOjQ0OjM1Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY
            3OTc4LW5vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXN
            fdXNlcl9ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjEiLCJyb3V0ZV9
            yZWFzb24iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImFkbWluIiwia25vd2xlZGdlIjoiZmFsc2UiLCJ",
            "status_code": 201,
            "status_text": "Created",
            "headers": [],
            "execution_time": 2638
        }
    ],
    "unserviced_requests": []
}