Buscar cabeçalhos - com escopo, global

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

    • A API Buscar cabeçalhos permite recuperar, definir, adicionar e remover cabeçalhos de uma lista de cabeçalhos de solicitação ou resposta.

    Esta API faz parte de um conjunto de APIs de busca, que fornecem várias ações para buscar recursos de sites externos. A coleção completa da API de busca inclui:

    Para oferecer suporte a ações de busca, a propriedade do sistema, glide.hosts.allowlist, permite controles sobre quais hosts um método de busca pode acessar. Aplica-se a APIs HTTP como RestMessageV2 e as mencionadas acima. Para obter mais informações sobre glide.hosts.allowlist, consulte Available system properties.

    Buscar cabeçalhos - Cabeçalhos (init)

    O construtor de cabeçalhos () cria um novo objeto de cabeçalhos vazio. Você também pode criar e preencher previamente um novo objeto Cabeçalhos com a lista de cabeçalhos HTTP usando o parâmetro init.

    Nota:
    Para adicionar cabeçalhos a um objeto Cabeçalhos existente, use Buscar cabeçalhos - append (nome da cadeia de caracteres, valor da cadeia de caracteres).
    Tabela 1. Parâmetros
    Nome Tipo Descrição
    inicializar Objeto Opcional. Um objeto literal que contém cabeçalhos HTTP para preencher previamente o novo objeto Cabeçalhos.
    Valores válidos:
    • Um objeto literal com valores de cadeia de caracteres,
    • Uma matriz de pares de nome-valor,
    • Um objeto de cabeçalhos existente (em que o novo objeto copia dados do objeto existente).

    Padrão: cria um objeto de cabeçalhos vazio

    O exemplo a seguir mostra como usar o construtor de cabeçalhos () para criar um novo objeto de cabeçalhos com e sem cabeçalhos.

    //Intializes an empty Headers object.
var headers = new Headers();

//Sets the new Headers object with a list of headers.
var httpHeaders = {
  "Content-Type": "application/json", 
  "X-My-Custom-Header": "XYZ", 
}; 

var myHeaders = new Headers(httpHeaders);

    Buscar cabeçalhos - append (nome da cadeia de caracteres, valor da cadeia de caracteres)

    Adiciona um novo valor a um cabeçalho existente dentro de um objeto Cabeçalhos ou adiciona o cabeçalho se ele ainda não existir.

    Se o cabeçalho especificado já existir, append() mudará o valor existente para o valor especificado. Se o cabeçalho especificado já existir e aceitar vários valores, append() anexará o novo valor ao final do conjunto de valores. Para substituir o valor antigo por um novo, use Buscar cabeçalhos - set (nome da cadeia de caracteres, valor da cadeia de caracteres).

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    nome Cadeia de caracteres Obrigatório. O nome do cabeçalho HTTP a ser adicionado ao objeto Cabeçalhos.
    valor Cadeia de caracteres Obrigatório. O valor do cabeçalho HTTP a ser adicionado.
    Tabela 3. Retornos
    Tipo Descrição
    Nenhum(a)

    O exemplo a seguir mostra como adicionar um cabeçalho usando append():

    var myHeaders = new Headers(); // Currently empty
myHeaders.append("Content-Type", "image/jpeg");
myHeaders.get("Content-Type"); // Returns 'image/jpeg'

    Saída:

    “image/jpeg”

    O exemplo a seguir mostra como anexar um novo cabeçalho que aceita vários valores:

    var myHeaders = new Headers(); // Currently empty
myHeaders.append("Accept-Encoding", "deflate");
myHeaders.append("Accept-Encoding", "gzip");
myHeaders.get("Accept-Encoding"); // Returns 'deflate, gzip'

    Saída:

    {“deflate”, “gzip”}

    Buscar cabeçalhos - delete(cadeia de caracteres name)

    Exclui um cabeçalho do objeto Cabeçalhos atual.

    Tabela 4. Parâmetros
    Nome Tipo Descrição
    nome Cadeia de caracteres O nome do cabeçalho HTTP a ser excluído do objeto Cabeçalhos.
    Tabela 5. Retornos
    Tipo Descrição
    Nenhum(a)

    O exemplo a seguir mostra como primeiro adicionar um cabeçalho ao objeto Cabeçalhos usando append()e, em seguida, excluir o mesmo cabeçalho usando delete().

    var myHeaders =newHeaders();// Currently empty
myHeaders.append("Content-Type","image/jpeg");
myHeaders.get("Content-Type");// Returns 'image/jpeg'

    O exemplo a seguir mostra que o endpoint retornará um valor nulo se o objeto Cabeçalhos já tiver sido excluído:

    myHeaders.delete("Content-Type");
myHeaders.get("Content-Type");// Returns null, as it has been deleted

    Saída:

    null

    Buscar cabeçalhos - entradas()

    Retorna um iterador que permite percorrer todos os pares de chave-valor (representados por cadeias de caracteres) contidos no objeto Cabeçalhos.

    Tabela 6. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 7. Retorna
    Tipo Descrição
    Iterador Retorna um objeto de iterador, em que os pares de chave e valor são objetos de cadeia de caracteres.

    O exemplo a seguir mostra como criar um objeto Cabeçalhos de teste e usar o método entradas() para retornar um iterador de todos os valores no objeto Cabeçalhos.

    // Create a test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/xml");
myHeaders.append("Vary", "Accept-Language");

// Display the key/value pairs
for (var pair of myHeaders.entries()) {
  console.log(`${pair[0]}: ${pair[1]}`);
}

    Saída:

    content-type: text/xml
vary: Accept-Language

    Buscar cabeçalhos - forEach(Function callbackFn, Object thisArg)

    Executa uma função de retorno de chamada uma vez para cada par de chave/valor no objeto Cabeçalhos.

    A função de retorno de chamada não é executada para chaves excluídas, mas sim para chaves existentes, mesmo se o valor for indefinido.

    Tabela 8. Parâmetros
    Nome Tipo Descrição
    retorno de chamadaFn Função Função a ser executada para cada par de chave/valor no objeto Cabeçalhos.

    Está em conformidade com o formato: callbackFn(string key, string value).
    callbackFn.value Cadeia de caracteres Valor da entrada do cabeçalho.
    callbackFn.key Cadeia de caracteres Nome da entrada do cabeçalho.
    callbackfn.object Cabeçalho O objeto Cabeçalhos a ser iterado.
    thisArg Objeto Valor a ser usado como este ao executar o retorno de chamada.
    Tabela 9. Retornos
    Tipo Descrição
    Nenhum(a)

    O exemplo a seguir registra uma linha para cada par de chave/valor no objeto Cabeçalhos:

    // Create a new test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Cookie", "This is a demo cookie");
myHeaders.append("compression", "gzip");

// Display the key/value pairs
myHeaders.forEach((value, key) => {
  console.log(`${key} ==> ${value}`);
});

    Saída:

    compression ==> gzip
content-type ==> application/json
cookie ==> This is a demo cookie

    Buscar cabeçalhos - get(String name)

    Retorna uma cadeia de caracteres de todos os valores de cabeçalho de um objeto de cabeçalhos especificado ou retorna nulo se o cabeçalho não existir.

    Tabela 10. Parâmetros
    Nome Tipo Descrição
    nome Cadeia de caracteres O nome do cabeçalho HTTP cujos valores de cabeçalho você deseja recuperar (sem distinção entre maiúsculas e minúsculas).
    Tabela 11. Retornos
    Tipo Descrição
    Cadeia de caracteres O valor do cabeçalho recuperado (representado como uma cadeia de caracteres) ou nulo se o cabeçalho não estiver definido.

    Retorna um erro se o cabeçalho não existir. Retorna um erro de tipo se o nome fornecido não for o de um cabeçalho HTTP.

    Veja a seguir como criar um objeto de cabeçalhos com vários cabeçalhos usando append()e retornar os valores do cabeçalho usando o método get().

    var myHeaders = new Headers(); // Currently empty
myHeaders.append("Accept-Encoding", "deflate");
myHeaders.append("Accept-Encoding", "gzip");
myHeaders.get("Accept-Encoding"); // Returns "deflate, gzip"
myHeaders
  .get("Accept-Encoding")
  .split(",")
  .map((v) => v.trimStart()); // Returns [ "deflate", "gzip"

    Saída:

    [ "deflate", "gzip" ]

    Buscar cabeçalhos - getSetCookie()

    Retorna todos os cabeçalhos Set-Cookie associados a uma resposta.

    Tabela 12. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 13. Retorna
    Tipo Descrição
    Matriz de cadeias de caracteres Uma matriz de cadeias de caracteres que contém os valores de todos os cabeçalhos Set-Cookie associados a uma resposta. O método retornará uma matriz vazia se nenhum cabeçalho Set-Cookie estiver definido.

    O exemplo de script a seguir mostra como usar getSetCookie() para retornar os valores de cabeçalho associados à resposta:

    var headers = new Headers({
  "Set-Cookie": "name1=value1",
});

headers.append("Set-Cookie", "name2=value2");

headers.getSetCookie();

    Saída:

    ["name1=value1", "name2=value2"]

    Buscar cabeçalhos - has(String name)

    Retorna um booliano que indica se um objeto Cabeçalhos contém o cabeçalho fornecido.

    Tabela 14. Parâmetros
    Nome Tipo Descrição
    nome Cadeia de caracteres O nome do cabeçalho HTTP para verificar se ele existe no objeto Cabeçalhos ou não.
    Tabela 15. Retornos
    Tipo Descrição
    Booliano Sinalizador que indica se o cabeçalho especificado existe no objeto Cabeçalhos. Um TypeError será retornado se o cabeçalho fornecido não for um nome de cabeçalho HTTP válido.
    Valores possíveis:
    • verdadeiro: o cabeçalho existe no objeto.
    • falso: o cabeçalho não existe no objeto.

    O exemplo a seguir usa os métodos Cabeçalhos() e append() para criar e definir um objeto Cabeçalhos com o cabeçalho Content-Type. O exemplo usa o método has() para mostrar que o cabeçalho Content-Type existe no objeto Cabeçalhos, mas um cabeçalho Accept-Coding não.

    var myHeaders = new Headers(); // Currently empty
myHeaders.append("Content-Type", "image/jpeg");
myHeaders.has("Content-Type"); // Returns true
myHeaders.has("Accept-Encoding"); // Returns false

    Saída:

    true
false

    Buscar cabeçalhos - chaves ()

    Retorna um iterador que permite percorrer todas as chaves contidas em um objeto Cabeçalhos.

    Use o método Buscar cabeçalhos - values() para retornar todas as chaves de cabeçalho.

    Tabela 16. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 17. Retorna
    Tipo Descrição
    Iterador Retorna um iterador, em que as chaves de cabeçalho são representadas como cadeias de caracteres.

    O exemplo a seguir mostra como criar um objeto Cabeçalhos com chaves e usar o método chaves () para retornar uma lista de cabeçalhos disponíveis.

    // Create a test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/xml");
myHeaders.append("Vary", "Accept-Language");

// Display the keys
for (var key of myHeaders.keys()) {
  console.log(key);
}

    Saída:

    content-type
vary

    Buscar cabeçalhos - set (nome da cadeia de caracteres, valor da cadeia de caracteres)

    Atualiza um valor de um cabeçalho existente dentro do objeto Cabeçalhos ou cria um novo cabeçalho com o valor fornecido se o cabeçalho ainda não existir.

    Para simplesmente anexar um novo valor a um cabeçalho existente sem substituir nenhum dado, use o método Buscar cabeçalhos - append (nome da cadeia de caracteres, valor da cadeia de caracteres).

    Tabela 18. Parâmetros
    Nome Tipo Descrição
    nome Cadeia de caracteres O nome do cabeçalho HTTP no qual um novo valor será definido. Lança TypeError se o nome fornecido não for o nome de um cabeçalho HTTP.
    valor Cadeia de caracteres O novo valor a ser definido para o cabeçalho fornecido.
    Tabela 19. Retornos
    Tipo Descrição
    Nenhum(a)

    O exemplo a seguir mostra como definir um cabeçalho no novo objeto Cabeçalhos usando append()e redefinir o valor usando set().

    var myHeaders = new Headers(); // Currently empty
myHeaders.append("Content-Type", "image/jpeg");
myHeaders.set("Content-Type", "text/html");

    Saída:

    text/html

    O exemplo a seguir mostra como definir um valor em um objeto Cabeçalhos quando ele aceita vários valores:

    myHeaders.set("Accept-Encoding", "deflate");
myHeaders.set("Accept-Encoding", "gzip");
myHeaders.get("Accept-Encoding");

    Saída:

    gzip

    Buscar cabeçalhos - values()

    Retorna um iterador que permite percorrer todos os valores de cabeçalho contidos no objeto Cabeçalhos.

    Use o método Buscar cabeçalhos - chaves () para retornar todos os valores de cabeçalho.

    Tabela 20. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 21. Retorna
    Tipo Descrição
    Cadeia de caracteres Retorna um iterador, em que os valores de cabeçalho são representados como cadeias de caracteres.

    O exemplo a seguir mostra como criar e definir primeiro um novo objeto Cabeçalhos com vários cabeçalhos usando o método append() e, em seguida, retornar uma lista de todos os valores de cabeçalho no novo objeto chamando o método values(). Console.log() registra a linha nos logs do sistema.

    // Create a test Headers object
var myHeaders = new Headers();
myHeaders.append("Content-Type", "text/xml");
myHeaders.append("Vary", "Accept-Language");

// Display the values
for (var value of myHeaders.values()) {
  console.log(value);
}

    Saída:

    text/xml
Accept-Language