Buscar resposta - com escopo, global

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

    • A API de busca de resposta fornece métodos para criar um novo objeto de resposta e para lidar com o corpo da resposta criado por um método de API de solicitação de busca.

    A API de resposta de busca 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.

    Propriedades da resposta

    A API de resposta fornece propriedades que retornam detalhes sobre a resposta HTTP. Essas propriedades permitem que você acesse metadados (como status, cabeçalhos, tipo) e o corpo da resposta (corpo) para processamento posterior. Eles permitem verificar o sucesso de uma solicitação (ok) e analisar os dados retornados em vários formatos (por exemplo, JSON ou texto). Essas propriedades são importantes para validar e manipular respostas do servidor em aplicações do lado do cliente. Para ler explicações mais detalhadas sobre cada propriedade, consulte https://developer.mozilla.org/en-US/docs/Web/API/Response.

    Tabela 1. Propriedades da resposta
    Nome da propriedade Descrição Exemplo
    corpo Somente pronto. Contém um fluxo legível de dados de bytes nos conteúdos do corpo da resposta.

    Valores válidos: um ReadableStream ou nulo.

    Tipo de dados: cadeia de caracteres

    		 
    const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.body; // ReadableStream
    corpoUsado Somente pronto. Sinalizador que indica se o corpo já foi lido.
    Valores aceitos:
    • verdadeiro: o corpo foi lido.
    • falso: o corpo não foi lido.

    Tipo de dados: booliano

    		 
    const request = new Request("/myEndpoint", {
  method: "POST",
  body: "Hello world",
});

request.bodyUsed; // false

request.text().then((bodyAsText) => {
  console.log(request.bodyUsed); // true
});
    cabeçalhos Somente leitura. O objeto de cabeçalhos associado à resposta.

    Tipo de dados: objeto de cabeçalhos

    		 
    const myRequest = new Request("flowers.jpg");
const myHeaders = myRequest.headers; // Headers {}
    ok Somente pronto. Sinalizador que indica se a resposta foi bem-sucedida (status no intervalo de 200 a 299) ou não.
    Valores aceitos:
    • verdadeiro: a resposta foi bem-sucedida.
    • falso: a resposta não foi bem-sucedida.

    Tipo de dados: booliano

    		 
    const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest).then((response) => {
  console.log(response.ok); // returns true if the response returned successfully
  response.blob().then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
});
    redirecionado Somente leitura. Sinalizador que indica se a resposta é um resultado de que a solicitação foi redirecionada.
    Valores aceitos:
    • verdadeiro: a solicitação foi redirecionada.
    • falso: a solicitação não foi redirecionada.

    Tipo de dados: booliano

    		 
    const myRequest = new Request("flowers.jpg");
const myCred = myRequest.redirect;
    status Somente leitura. Códigos de status HTTP da resposta. Por exemplo, 200 para sucesso.

    Tipo de dados: número

    		 
    const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => {
    console.log("response.status =", response.status); // response.status = 200
    return response.blob();
  })
  .then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
    StatusText Somente leitura. Mensagem de status correspondente ao código de status HTTP em response.status. Por exemplo, isso seria OK para um código de status 200, Continuar para 100, Não encontrado para 404.

    Tipo de dados: cadeia de caracteres

    		 
    const myRequest = new Request("flowers.jpg");

 // Log the HTTP status and status text
    console.log(`Status: ${response.status}`);
    console.log(`Status Text: ${response.statusText}`);
    
    // Check if the response is successful
    if (response.ok) {
      console.log("Request succeeded!");
    } else {
      console.log("Request failed.");
    }
  } catch (error) {
    console.error("Error fetching the URL:", error);
  }
}
    tipo Somente leitura. Tipo de resposta.
    Valores aceitos:
    • basic: resposta normal, da mesma origem, com todos os cabeçalhos expostos, exceto "Set-Cookie".
    • cors: a resposta foi recebida de uma solicitação entre origens válida. Certos cabeçalhos e o corpo podem ser acessados.
    • erro: erro de rede. Não há informações úteis que descrevam o erro. O status da resposta é 0, os cabeçalhos estão vazios e são imutáveis. Este é o tipo de resposta obtido de Response.error().
    • opaque: resposta da solicitação "no-cors" para o recurso de origem cruzada. Severamente restrito.
    • opaqueredirect: a solicitação de busca foi feita com o redirecionamento: "manual". O status da resposta é 0, os cabeçalhos estão vazios, o corpo é nulo e o rodapé está vazio.

    Tipo de dados: cadeia de caracteres

    		 
    const myImage = document.querySelector("img");

const myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => {
    console.log("response.type =", response.type); // response.type = 'basic'
    return response.blob();
  })
  .then((myBlob) => {
    const objectURL = URL.createObjectURL(myBlob);
    myImage.src = objectURL;
  });
    URL Somente leitura. URL da resposta.

    Tipo de dados: cadeia de caracteres

    		 
    const myRequest = new Request("flowers.jpg");
const myURL = myRequest.url; // "https://github.com/mdn/dom-examples/tree/main/fetch/fetch-request/flowers.jpg"

    Buscar resposta - Resposta (corpo do objeto, opções de objeto)

    Cria um novo objeto de resposta usando o construtor Response().

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    corpo Objeto Opcional. Um objeto que define um corpo para a resposta.
    Tipos válidos:
    • ArrayBuffer
    • Blob
    • Exibição de dados
    • FormData
    • ReadableStream
    • Cadeia de caracteres
    • Literal de cadeia de caracteres
    • TypedArray
    • URLSearchParams

    Padrão: nulo
    opções Objeto Opcional. Um objeto de opções que contém todas as configurações personalizadas que você deseja aplicar à resposta ou um objeto vazio (que é o valor padrão). As opções possíveis são:
    • cabeçalhos: todos os cabeçalhos que você deseja adicionar à sua resposta, contidos em um objeto Buscar cabeçalhos - com escopo, global ou objeto literal de pares de chave/valor de cadeia de caracteres (consulte cabeçalhos HTTP para obter uma referência). Vazio por padrão.
    • status: o código de status da resposta. O valor padrão é 200.
    • statusText: a mensagem de status associada ao código de status, como "OK". O valor padrão é "".

    Neste exemplo, criamos um novo objeto de resposta usando o construtor, passando um novo Blob como um corpo e um objeto de inicialização contendo opções personalizadas de status e statusText:

    const myBlob = new Blob();
const myOptions = { status: 200, statusText: "Status message!" };
const myResponse = new Response(myBlob, myOptions);

    Buscar resposta - arrayBuffer()

    Retorna uma promessa que é resolvida com um ArrayBuffer.

    O método arrayBuffer() é útil ao trabalhar com dados binários, como imagens, arquivos de áudio ou qualquer outro arquivo binário que precise ser processado.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 4. Retorna
    Tipo Descrição
    Objeto Uma promessa que é resolvida com um ArrayBuffer, que representa um buffer de dados binários brutos genéricos.
    Tabela 5. Exceções
    Exceção Descrição
    DOMException – AbortError Uma exceção informando que a solicitação foi anulada.
    Erro de tipo Lançado por um dos seguintes motivos:
    • O corpo da resposta está com problemas ou bloqueado.
    • Houve um erro ao decodificar o conteúdo do corpo (por exemplo, porque o cabeçalho Content-Encoding está incorreto).
    Erro de intervalo Houve um problema ao criar o ArrayBufferassociado. Por exemplo, se o tamanho dos dados for muito grande.
    O script de exemplo a seguir busca dados binários de um servidor e os processa enquanto utiliza o método arrayBuffer() seguindo estas etapas:
    1. fetch(): busca um recurso da URL especificada.
    2. response.ok: verifica se o status da resposta está no intervalo de 200 a 299.
    3. arrayBuffer(): lê o corpo da resposta e o converte em um ArrayBuffer, que representa um buffer de dados binários brutos genérico de comprimento fixo.
    4. Uint8Array: converte o ArrayBuffer em um Uint8Array, que é uma matriz digitada para facilitar a manipulação de dados binários.
    javascriptCopy code// Simple API to fetch binary data and process it using arrayBuffer()asyncfunctionfetchBinaryData(url) {
  try {
    // Fetch the resource from the provided URLconst response = awaitfetch(url);

    // Check if the response is successfulif (!response.ok) {
      thrownewError(`HTTP error! Status: ${response.status}`);
    }

    // Convert the response body to an ArrayBufferconst arrayBuffer = await response.arrayBuffer();

    // Process the ArrayBuffer (e.g., convert it to a typed array)const uint8Array = newUint8Array(arrayBuffer);

    // Return the processed datareturn uint8Array;
  } catch (error) {
    console.error("Error fetching or processing binary data:", error);
    throw error;
  }
}

// Example usageconst binaryDataUrl = 'https://example.com/path/to/binary/data';

fetchBinaryData(binaryDataUrl)
  .then((data) => {
    console.log("Binary data as Uint8Array:", data);
    // Further processing can be done here, e.g., rendering an image or playing audio
  })
  .catch((error) => {
    console.error("Failed to fetch binary data:", error);
  });

    Buscar resposta - blob()

    Retorna uma promessa que é resolvida com um Blob.

    Tabela 6. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 7. Retorna
    Tipo Descrição
    Objeto Uma promessa que é resolvida com um Blob.
    Tabela 8. Exceções
    Exceção Descrição
    DOMException – AbortError Uma exceção informando que a solicitação foi anulada.
    Erro de tipo Lançado por um dos seguintes motivos:
    • O corpo da resposta está com problemas ou bloqueado.
    • Houve um erro ao decodificar o conteúdo do corpo (por exemplo, porque o cabeçalho Content-Encoding está incorreto).
    O exemplo a seguir demonstra como usar o método blob() com a API de busca usando as etapas a seguir. Este caso de uso é ótimo para buscar imagens ou outro conteúdo binário (como vídeos ou PDFs) e exibi-los dinamicamente.
    1. fetch(url): busca um recurso da URL especificada.
    2. response.blob(): converte o corpo da resposta em um objeto Blob, que representa dados binários.
    3. URL.createObjectURL(blob): gera um URL temporário para o blob, que pode ser usado no DOM (por exemplo, como uma origem de imagem).
    4. Anexação da imagem ao DOM: cria dinamicamente um elemento de imagem, define a URL do blob como sua origem e a anexa ao corpo do documento.
    
async function fetchBlob(url) {
  try {
    // Fetch the resource from the provided URL
    const response = await fetch(url);

    // Check if the response is successful
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    // Convert the response body to a Blob
    const blob = await response.blob();

    // Create a URL for the Blob and log it
    const blobUrl = URL.createObjectURL(blob);
    console.log("Blob URL:", blobUrl);

    // For example, you can set it as the source of an image
    const img = document.createElement('img');
    img.src = blobUrl;
    img.alt = "Fetched Blob Image";
    document.body.appendChild(img);
  } catch (error) {
    console.error("Error fetching or processing blob:", error);
  }
}

// Example usage with an image URL
const imageUrl = 'https://via.placeholder.com/150';
fetchBlob(imageUrl);

    Buscar resposta - bytes()

    Retorna uma promessa que é resolvida com um Uint8Array.

    Tabela 9. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 10. Retorna
    Tipo Descrição
    Objeto Uma promessa que é resolvida com um Uint8Array.
    Tabela 11. Exceções
    Exceção Descrição
    DOMException - AbortError A solicitação foi anulada.
    Erro de tipo Lançado por um dos seguintes motivos:
    • O corpo da resposta está com problemas ou bloqueado.
    • Houve um erro ao decodificar o conteúdo do corpo (por exemplo, porque o cabeçalho Content-Encoding está incorreto).
    Erro de intervalo Houve um problema ao criar o ArrayBufferassociado. Por exemplo, se o tamanho dos dados for muito grande.

    O exemplo a seguir mostra como buscar um arquivo de texto, retornar o corpo como um Uint8Array e decodificá-lo em uma cadeia de caracteres.

    const response = await fetch("https://www.example.com/textfile.txt");
const textFile = await response.bytes();
const string = new TextDecoder().decode(textFile);
console.log(string);

    Buscar resposta - formData()

    Retorna uma promessa que é resolvida com um objeto FormData.

    Tabela 12. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 13. Retorna
    Tipo Descrição
    Objeto Uma promessa que é resolvida com um objeto FormData.
    Tabela 14. Exceções
    Exceção Descrição
    DOMException - AbortError A solicitação foi anulada.
    Erro de tipo Lançado por um dos seguintes motivos:
    • O corpo da resposta está com problemas ou bloqueado.
    • Houve um erro ao decodificar o conteúdo do corpo (por exemplo, porque o cabeçalho Content-Encoding está incorreto).
    O exemplo a seguir demonstra como usar formData() para processar uma resposta de envio de formulário usando as seguintes etapas:
    1. Corpo da solicitação: JSON.stringify() usado para enviar os dados do formulário como JSON em vez de parâmetros codificados por URL.
    2. Tipo de conteúdo: defina como application/json para indicar o formato do corpo da solicitação.
    // Example of using Response.formData()
async function fetchFormData(url) {
  try {
    // Make a POST request to fetch the form data
    const response = await fetch(url, {
      method: 'POST',
      body: JSON.stringify({
        name: 'John Doe',
        email: 'john.doe@example.com',
      }),
      headers: {
        'Content-Type': 'application/json',
      },
    });

    // Check if the response is successful
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    // Parse the response as FormData
    const formData = await response.formData();

    // Iterate through the FormData entries
    for (const [key, value] of formData.entries()) {
      console.log(`${key}: ${value}`);
    }
  } catch (error) {
    console.error("Error fetching or processing form data:", error);
  }
}

// Example usage
const formEndpoint = 'https://httpbin.org/post'; // Replace with your form endpoint
fetchFormData(formEndpoint);

    Saída:

    name: John Doe
email: john.doe@example.com

    Buscar resposta - json()

    Retorna uma promessa que é resolvida para o resultado da análise do texto do corpo como JSON.

    Nota:
    Apesar do nome deste método, o resultado de json() não é JSON, mas sim o resultado de usar JSON como entrada e analisá-lo para produzir um objeto JavaScript.
    Tabela 15. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 16. Retorna
    Tipo Descrição
    Objeto Uma promessa que é resolvida para um objeto JavaScript. Este objeto pode ser qualquer coisa que possa ser representada por JSON, como um objeto, matriz, cadeia de caracteres, número e assim por diante.
    Tabela 17. Exceções
    Exceção Descrição
    DOMException - AbortError A solicitação foi anulada.
    Erro de tipo Lançado por um dos seguintes motivos:
    • O corpo da resposta está com problemas ou bloqueado.
    • Houve um erro ao decodificar o conteúdo do corpo (por exemplo, porque o cabeçalho Content-Encoding está incorreto).
    Erro de Sintaxe O corpo da resposta não pode ser analisado como JSON.
    O exemplo a seguir demonstra como usar json() para formar uma resposta:
    1. fetch() faz uma solicitação GET para a URL.
    2. O response.ok verifica se a solicitação foi bem-sucedida (código de status 200–299).
    3. Se for bem-sucedido, response.json() será chamado para analisar os dados JSON da resposta.
    4. Os dados analisados são registrados nos logs do sistema usando a API do Console. Se ocorrer algum erro durante a solicitação ou análise, ele será detectado e registrado.
    fetch('https://jsonplaceholder.typicode.com/posts/1')
  .then(response => {
    if (!response.ok) {
      throw new Error('Network response was not ok');
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Fetch error:', error));

    Buscar resposta - text()

    Lê o corpo da resposta e o retorna como uma cadeia de caracteres simples. A resposta é sempre decodificada usando UTF-8.

    O método text() é útil para respostas que contêm dados textuais, como HTML, JSON (se você quiser manipulá-los manualmente), XML ou arquivos de texto sem formatação que devem ser tratados como cadeias de caracteres sem formatação.

    Tabela 18. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 19. Retorna
    Tipo Descrição
    Nenhum(a) Uma promessa que é resolvida com uma cadeia de caracteres codificada em UTF-8.
    Tabela 20. Exceções
    Exceção Descrição
    DOMException - AbortError A solicitação foi anulada.
    Erro de tipo Lançado por um dos seguintes motivos:
    • O corpo da resposta está com problemas ou bloqueado.
    • Houve um erro ao decodificar o conteúdo do corpo (por exemplo, porque o cabeçalho Content-Encoding está incorreto).

    O exemplo a seguir mostra como uma maneira simples de usar text() quando o servidor retorna texto sem formatação, como Olá, mundo! Esta é uma amostra de resposta.

    const response = awaitfetch('https://example.com/text-endpoint');
const text = await response.text();
console.log(text); // Outputs: Hello, world! This is a sample response.

    Saída:

    Hello, world! This is a sample response.