Buscar solicitação - Escopo, Global

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

    • . Buscar solicitação A API contém métodos para criar ou recuperar um objeto de solicitação para permitir que as aplicações solicitem recursos de forma assíncrona, como JSON, texto ou dados binários, de um servidor, e manipulam a resposta. Esta API oferece suporte a vários métodos HTTP, como GET, POST, PUT, DELETE e assim por diante.

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

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

    Propriedades da solicitação

    . Buscar solicitação A API oferece suporte a várias propriedades somente leitura que oferecem informações detalhadas sobre uma solicitação HTTP. Alguns deles incluem url (O URL da solicitação), método (O método HTTP), cabeçalhos (os cabeçalhos associados), e. corpo (o corpo da solicitação como um fluxo). Outras propriedades incluem configurações para cache, credenciais e referenciadores. Essas propriedades são somente leitura, o que significa que elas podem ser acessadas, mas não modificadas após a criação da solicitação. Para ler mais sobre cada propriedade, consulte https://developer.mozilla.org/en-US/docs/Web/API/Request.

    Tabela 1. Propriedades da solicitação
    Nome da propriedade Descrição Exemplo
    corpo Propriedade somente pronta. Contém um fluxo legível de dados de bytes com o conteúdo do corpo que foi adicionado à solicitação.

    Tipo/valor de dados: Um ReadableStream ou nulo.

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

request.body; // ReadableStream
    Corpo usado Propriedade somente pronta. Sinalizador que indica se o corpo da solicitação ainda foi lido.
    Valor aceito:
    • Verdadeiro: O corpo da solicitação foi lido.
    • Falso: O corpo da solicitação 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
});
    cache Propriedade somente pronta. Contém o modo de cache da solicitação que controla como a solicitação interage com o cache HTTP do navegador.
    Valores aceitos:
    • Padrão: O navegador procura uma solicitação correspondente em seu cache HTTP.
      • Se houver uma correspondência e ela for nova, ela será retornada do cache.
      • Se houver uma correspondência, mas estiver obsoleta, o navegador fará uma solicitação condicional para o servidor remoto. Se o servidor indicar que o recurso não foi alterado, ele será retornado do cache. Caso contrário, o recurso será baixado do servidor e o cache será atualizado.
      • Se não houver correspondência, o navegador fará uma solicitação normal e atualizará o cache com o recurso baixado.
    • Force-cache: O navegador procura uma solicitação correspondente em seu cache HTTP.
      • Se houver uma correspondência, nova ou obsoleta, ela será retornada do cache.
      • Se não houver correspondência, o navegador fará uma solicitação normal e atualizará o cache com o recurso baixado.
    • sem cache: O navegador procura uma solicitação correspondente em seu cache HTTP.
      • Se houver uma correspondência, nova ou obsoleta, o navegador fará uma solicitação condicional para o servidor remoto. Se o servidor indicar que o recurso não foi alterado, ele será retornado do cache. Caso contrário, o recurso será baixado do servidor e o cache será atualizado.
      • Se não houver correspondência, o navegador fará uma solicitação normal e atualizará o cache com o recurso baixado.
    • no-store: O navegador busca o recurso do servidor remoto sem primeiro olhar no cache e não atualiza o cache com o recurso baixado.
    • Somente se estiver em cache: O navegador procura uma solicitação correspondente em seu cache HTTP.
      • Se houver uma correspondência, nova ou obsoleta, ela será retornada do cache.
      • Se não houver correspondência, o navegador responderá com o status de tempo limite do gateway 504.

      . somente se armazenado em cache o modo só pode ser usado se o modo da solicitação for mesma origem . Redirecionamentos em cache serão seguidos se a solicitação for redirecionar a propriedade é seguir e os redirecionamentos não violam mesma origem modo.

    • Recarregamento: O navegador busca o recurso do servidor remoto sem primeiro pesquisar o cache, mas atualiza o cache com o recurso baixado.

    Tipo de dados: Cadeia de caracteres

    		 
    // Download a resource with cache busting, to bypass the cache
// completely.
fetch("some.json", { cache: "no-store" }).then((response) => {
  /* consume the response */
});

// Download a resource with cache busting, but update the HTTP
// cache with the downloaded resource.
fetch("some.json", { cache: "reload" }).then((response) => {
  /* consume the response */
});

// Download a resource with cache busting when dealing with a
// properly configured server that will send the correct ETag
// and Date headers and properly handle If-Modified-Since and
// If-None-Match request headers, therefore we can rely on the
// validation to guarantee a fresh response.
fetch("some.json", { cache: "no-cache" }).then((response) => {
  /* consume the response */
});

// Download a resource with economics in mind! Prefer a cached
// albeit stale response to conserve as much bandwidth as possible.
fetch("some.json", { cache: "force-cache" }).then((response) => {
  /* consume the response */
});

// Naive stale-while-revalidate client-level implementation.
// Prefer a cached albeit stale response; but update if it's too old.
// AbortController and signal to allow better memory cleaning.
// In reality; this would be a function that takes a path and a
// reference to the controller since it would need to change the value
let controller = new AbortController();
fetch("some.json", {
  cache: "only-if-cached",
  mode: "same-origin",
  signal: controller.signal,
})
  .catch((e) =>
    e instanceof TypeError && e.message === "Failed to fetch"
      ? { status: 504 } // Workaround for chrome; which fails with a TypeError
      : Promise.reject(e),
  )
  .then((res) => {
    if (res.status === 504) {
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "force-cache",
        mode: "same-origin",
        signal: controller.signal,
      });
    }
    const date = res.headers.get("date"),
      dt = date ? new Date(date).getTime() : 0;
    if (dt < Date.now() - 86_400_000) {
      // if older than 24 hours
      controller.abort();
      controller = new AbortController();
      return fetch("some.json", {
        cache: "reload",
        mode: "same-origin",
        signal: controller.signal,
      });
    }

    // Other possible conditions
    if (dt < Date.now() - 300_000)
      // If it's older than 5 minutes
      fetch("some.json", { cache: "no-cache", mode: "same-origin" }); // no cancellation or return value.
    return res;
  })
  .then((response) => {
    /* consume the (possibly stale) response */
  })
  .catch((error) => {
    /* Can be an AbortError/DOMException or a TypeError */
  });
    credenciais Somente leitura. Reflete o valor fornecido ao Solicitação () construtor na opção de credenciais. Credenciais são cookies, certificados de cliente TLS ou cabeçalhos de autenticação que contêm um nome de usuário e senha.
    Valores aceitos:
    • Incluir: Sempre inclua credenciais, mesmo para solicitações de origem cruzada.
    • Omitir: Nunca envie credenciais na solicitação ou inclua credenciais na resposta.
    • Mesma origem: Envie e inclua credenciais somente para solicitações da mesma origem.

    Tipo de dados: Cadeia de caracteres

    		 
    const request = new Request("flowers.jpg");
const request = request.request; // returns "same-origin" by default
    destino Somente leitura. Retorna uma cadeia de caracteres que descreve o tipo de conteúdo solicitado.
    Valores aceitos:
    • Áudio: O destino são dados de áudio.
    • Audioworklet: O destino são os dados que estão sendo obtidos para uso por um worklet de áudio.
    • Documento: O destino é um documento HTML ou XML.
    • Incorporar: O marcador é conteúdo incorporado.
    • Fencedframe: O destino é um quadro cercado.
    • Fonte: O destino é uma fonte.
    • Quadro: O destino é um quadro.
    • iframe: O destino é um iframe.
    • Imagem: O destino é uma imagem.
    • json: O destino é um arquivo JSON
    • Manifesto: O destino é um manifesto.
    • Objeto: O destino é um objeto.
    • Paintworklet: O destino é uma worklet de pintura.
    • Relatório: O destino é um relatório.
    • Script: O destino é um script.
    • Sharedworker: O destino é um trabalhador compartilhado.
    • Estilo: O destino é um estilo.
    • Trilha: O destino é um HTML <track>.
    • Vídeo: O destino são dados de vídeo.
    • Trabalhador: O destino é um trabalhador.
    • xslt: O destino é uma transformação XSLT.

    Tipo de dados: Cadeia de caracteres

    		 
    fetch('https://example.com/image.jpg', {
  destination: 'image'
})
  .then(response => response.blob())
  .then(blob => {
    console.log('Image fetched successfully', blob);
  })
  .catch(error => console.error('Error:', error));
    cabeçalhos Somente leitura. O objeto Cabeçalhos associado à solicitação.

    Tipo de dados: Objeto de cabeçalhos

    		 
    const myRequest = new Request("flowers.jpg");
const myHeaders = myRequest.headers; // Headers {}
    integridade Somente leitura. O valor de integridade do subrecurso da solicitação.

    Valor: O valor que foi passado como options.integrityargumento ao criar a solicitação. Se uma integridade não tiver sido especificada, a propriedade retornará '' .

    		 
    const myRequest = new Request("flowers.jpg", {
  integrity: "sha256-abc123",
});
console.log(myRequest.integrity); // "sha256-abc123"
    ÉHistóriaNavegação Somente leitura. Booliano que indica se a solicitação é uma navegação de histórico.
    Valores aceitos:
    • Verdadeiro: A solicitação é uma navegação de histórico.
    • Falso: A solicitação não é uma navegação de histórico.

    Tipo de dados: Booliano

    		 
    self.addEventListener("request", (event) => {
  // ...

  if (event.request.isHistoryNavigation) {
    event.respondWith(
      caches.match(event.request).then((response) => {
        if (response !== undefined) {
          return response;
        } else {
          return fetch(event.request).then((response) => {
            let responseClone = response.clone();

            caches.open("v1").then((cache) => {
              cache.put(event.request, responseClone);
            });

            return response;
          });
        }
      }),
    );
  }

  // ...
});
    keepalive Somente leitura. A configuração de keepalive da solicitação (verdadeiro ou falso). Retorna uma cadeia de caracteres vazia se um valor de integridade não for passado na solicitação.
    Valores aceitos:
    • Verdadeiro: O navegador mantém a solicitação associada ativa se a página que a iniciou for descarregada antes da conclusão da solicitação.
    • Falso: O navegador não manterá a solicitação associada ativa se a página que a iniciou for descarregada antes da conclusão da solicitação.

    Tipo de dados: Booliano

    		 
    const options = {
  keepalive: true,
};

const myRequest = new Request("flowers.jpg", options);
let myKeepAlive = myRequest.keepalive; // true
    method Somente leitura. O método da solicitação ( OBTER , PUBLICAR etc.)

    Tipo de dados: Cadeia de caracteres

    		 
    const myRequest = new Request("flowers.jpg");
const myMethod = myRequest.method; // GET
    modo Somente leitura. Modo da solicitação. Usado para determinar se as solicitações de origem cruzada levam a respostas válidas e quais propriedades da resposta são legíveis.
    Valores aceitos:
    • cors: Se a solicitação for de origem cruzada, ela usará o mecanismo CORS (Cross-Origin Resource Sharing, compartilhamento de recursos entre origens).
    • Navegar: Um modo para oferecer suporte à navegação. O valor Navegar deve ser usado somente pela navegação HTML. Uma solicitação Navegar é criada somente durante a navegação entre documentos.
    • no-cors: Desabilita CORS para solicitações de origem cruzada. A resposta é opaca, o que significa que seus cabeçalhos e corpo não estão disponíveis para JavaScript.
    • Same-origin: Não permite solicitações de origens cruzadas. Se uma solicitação for feita para outra origem com este modo definido, o resultado será um erro.

    As solicitações podem ser iniciadas de várias maneiras, e o modo de uma solicitação depende dos meios específicos pelos quais ela foi iniciada. Por exemplo, quando um objeto de solicitação é criado usando Solicitação () Construtor, o valor da propriedade de modo para essa solicitação é definido como cors. No entanto, para solicitações criadas que não sejam pelo Solicitação () construtor, o no-cors é normalmente usado como o modo; por exemplo, para recursos incorporados em que a solicitação é iniciada a partir da marcação, a menos que o atributo crossorigin esteja presente, a solicitação é feita na maioria dos casos usando o modo no-cors, ou seja, para <link>ou <script> elements (except when used with modules), or <img>, <audio>,<video>, <object>, <embed>, or <iframe> elements.

    Tipo de dados: Cadeia de caracteres

    		 
    const myRequest = new Request("flowers.jpg");
const myMode = myRequest.mode; // returns "cors" by default
    redirect Somente leitura. Modo de como os redirecionamentos são manipulados.
    Valores válidos:
    • erro
    • seguir
    • manual

    Tipo de dados: Cadeia de caracteres

    Padrão: Seguir

    		 
    const myRequest = new Request("flowers.jpg");
const myCred = myRequest.redirect;
    referenciador Somente leitura. O referenciador da solicitação (por exemplo, cliente , não referenciador Ou um URL). Um valor de não referenciador retorna uma cadeia de caracteres vazia.

    Tipo de dados: Cadeia de caracteres

    		 
    const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrer; // returns "about:client" by default
    ReferrerPolicy Somente leitura. A política de referenciador que controla quais informações de referenciador são enviadas no cabeçalho do referenciador com a solicitação.

    Tipo de dados: Cadeia de caracteres

    		 
    const myRequest = new Request("flowers.jpg");
const myReferrer = myRequest.referrerPolicy; // returns "" by default
    sinal Somente leitura. AbortSignal associado à solicitação.

    Tipo de dados: Cadeia de caracteres

    		 
    // Create a new abort controller
const controller = new AbortController();

// Create a request with this controller's AbortSignal object
const req = new Request("/", { signal: controller.signal });

// Add an event handler logging a message in case of abort
req.signal.addEventListener("abort", () => {
  console.log("abort");
});

// In case of abort, log the AbortSignal reason, if any
fetch(req).catch(() => {
  if (req.signal.aborted) {
    if (req.signal.reason) {
      console.log(`Request aborted with reason: ${req.signal.reason}`);
    } else {
      console.log("Request aborted but no reason was given.");
    }
  } else {
    console.log("Request not aborted, but terminated abnormally.");
  }
});

// Actually abort the request
controller.abort();
    URL Somente leitura. URL da solicitação.

    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 solicitação - request()

    Cria um novo objeto de solicitação. Opcionalmente, crie o objeto de solicitação a partir de um URL ou recurso de objeto.

    Tabela 2. Parâmetros
    Nome Tipo Descrição
    entrada Cadeia de caracteres ou objeto Opcional. O recurso a ser recuperado.

    Valores válidos:

    • Uma cadeia de caracteres que contém o URL do recurso a ser obtido. A API não aceita URLs que contenham credenciais, como http://user.password.example.com . Uma exceção será lançada se o URL não puder ser analisado.
    • Um objeto de solicitação, criando efetivamente uma cópia de um objeto de solicitação existente. A estrutura do objeto é ditada pela classe de solicitação.
      Nota:
      Observe as seguintes atualizações comportamentais para manter a segurança e tornar o construtor menos propenso a lançar exceções:
      • Se este objeto existir em outra origem para a chamada do construtor, a  propriedade request.referrer será removida.
      • Se este objeto tiver uma  propriedade request.mode de  navegar , o  valor do modo é convertido para  mesma origem .
    opções Objeto Opcional. . Buscar SolicitInit - Escopo, Global objeto que contém configurações personalizadas a serem aplicadas à solicitação. Se você criar uma nova solicitação a partir de uma solicitação existente, as opções definidas na nova solicitação substituirão todas as opções correspondentes na solicitação original.

    Padrão: Retorna valores padrão para todas as propriedades.

    O exemplo a seguir mostra como criar um novo objeto de solicitação usando Solicitação () construtor.

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

    O exemplo a seguir mostra como criar o novo objeto de solicitação usando o parâmetro de entrada para recuperar uma URL ou objeto.

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then((response) => response.blob())
  .then((response) => {
    var objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });

    O exemplo a seguir mostra como criar o novo objeto de solicitação com opções de cabeçalho usando um objeto literal.

    var myImage = document.querySelector("img");
var myRequest = new Request("flowers.jpg");

var options = {
  headers: {
    "Cache-Control": "max-age=60480",
  },
};

    Buscar solicitação - arrayBuffer()

    Lê o corpo da solicitação e o retorna como uma promessa que resolve com um arrayBuffer.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 4. Retorna
    Tipo Descrição
    Promessa Uma promessa que resolve com um ArrayBuffer .

    A seguir, é mostrado como criar uma nova solicitação usando ArrayBuffer() método.

    var myArray = new Uint8Array(10);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myArray,
});

request.arrayBuffer().then((buffer) => {
  // perform an action with the buffer sent in the request
});

    Buscar solicitação - blob()

    Lê o corpo da solicitação e o retorna como uma promessa que resolve com um blob.

    Tabela 5. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 6. Retorna
    Tipo Descrição
    Objeto Uma promessa que resolve com um Blob .

    O exemplo a seguir mostra como formar uma solicitação com blob() método.

    var obj = { hello: "world" };
var myBlob = new Blob([JSON.stringify(obj, null, 2)], {
  type: "application/json",
});

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myBlob,
});

request.blob().then((myBlob) => {
  // do something with the blob sent in the request
});

    Buscar solicitação - bytes ()

    Lê o corpo da solicitação e o retorna como uma promessa que resolve com um Uint8Array.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 8. Retorna
    Tipo Descrição
    Objeto Uma promessa que resolve com um Uint8Array .

    A seguir, é mostrado como criar uma nova solicitação usando bytes() método.

    var myArray = new Uint8Array(10);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: myArray,
});

request.bytes().then((buffer) => {
  // do something with the buffer sent in the request
});

    Buscar solicitação - clone()

    Cria uma cópia do objeto de solicitação atual.

    Tabela 9. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 10. Retorna
    Tipo Descrição
    Solicitação Um objeto de solicitação que é uma cópia exata da solicitação clonar() foi chamado em. clonar() gera um erro se o corpo da solicitação já tiver sido usado. Se você quiser modificar a solicitação, use Buscar solicitação - request() construtor.

    O exemplo a seguir demonstra como criar uma nova solicitação usando solicitação () e, em seguida, copie-o usando clonar() .

    var myRequest = new Request("flowers.jpg");
var newRequest = myRequest.clone(); // a copy of the request is now stored in newRequest

    Buscar solicitação - formData()

    Lê o corpo da solicitação e o retorna como uma promessa que é resolvida com um objeto FormData.

    Tabela 11. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 12. Retorna
    Tipo Descrição
    Nenhum(a) Uma promessa que resolve com um FormData objeto.

    O exemplo a seguir demonstra como criar uma nova solicitação usando solicitação () E resolva-o com o método formData() para resolvê-lo como um objeto FormData.

    var formData = new FormData();
var fileField = document.querySelector('input[type="file"]');

formData.append("username", "abc123");
formData.append("avatar", fileField.files[0]);

var request = new Request("/myEndpoint", {
  method: "POST",
  body: formData,
});

request.formData().then((data) => {
  // do something with the formdata sent in the request
});

    Buscar solicitação - json()

    Lê o corpo da solicitação, analisa o conteúdo como JSON e retorna uma promessa que é resolvida com o resultado analisado.

    Tabela 13. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 14. Retorna
    Tipo Descrição
    Objeto Uma promessa (a eventual conclusão ou falha de uma operação assíncrona e seu valor resultante) que resolve um objeto JavaScript. Este objeto pode ser qualquer coisa que possa ser representada por JSON: Um objeto, uma matriz, uma cadeia de caracteres, um número e assim por diante.

    O exemplo a seguir demonstra como criar uma nova solicitação usando solicitação () e então json() Para analisar a solicitação e devolvê-la como um objeto JSON.

    var obj = { hello: "world" };

var request = new Request("/myEndpoint", {
  method: "POST",
  body: JSON.stringify(obj),
});

request.json().then((data) => {
  // process the data sent in the request
});

    Buscar solicitação - text()

    Lê o corpo da solicitação e o retorna como uma promessa que resolve com uma cadeia de caracteres decodificada usando UTF-8.

    Tabela 15. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 16. Retorna
    Tipo Descrição
    Nenhum(a) Uma promessa que resolve com uma cadeia de caracteres no formato UTF-8.

    Este exemplo mostra como chamar texto () .

    var text = "Hello world";

var request = new Request("/myEndpoint", {
  method: "POST",
  body: text,
});

request.text().then((text) => {
  // process the data sent in the request
});