Buscar solicitação - com escopo, global

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

    • A API de solicitação de busca 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 manipulem 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 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 solicitação

    A API de solicitação de busca 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 de cache, credenciais e referenciadores. Essas propriedades são somente leitura, o que significa que podem ser acessadas, mas não modificadas, depois que a solicitação é criada. 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
    corpoUsado Propriedade somente pronta. Sinalizador que indica se o corpo da solicitação já 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 atualizada, ela será retornada do cache.
      • Se houver uma correspondência, mas ela estiver obsoleta, o navegador fará uma solicitação condicional ao 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.
    • no-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 ao 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 consultar o cache e não atualiza o cache com o recurso baixado.
    • somente se 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.

      O modo somente se em cache só poderá ser usado se o modo da solicitação for same-origin. Os redirecionamentos em cache serão seguidos se a propriedade de redirecionamento da solicitação for seguir e os redirecionamentos não violarem o modo de mesma origem.

    • recarregar: o navegador busca o recurso do servidor remoto sem primeiro consultar 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 construtor Request() na opção de credenciais. As 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:
    • include: sempre inclua credenciais, mesmo para solicitações entre origens.
    • omitir: nunca envie credenciais na solicitação ou inclua credenciais na resposta.
    • same-origin: envia e inclui credenciais somente para solicitações de same-origin.

    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 que está sendo solicitado.
    Valores aceitos:
    • audio: 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.
    • embed: o taget é um conteúdo incorporado.
    • FencedFrame: o destino é um quadro fechado.
    • 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 é um 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.
    • rastrear: 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 de 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 de sub-recurso da solicitação.

    Valor: o valor que foi passado como o argumento options.integrity ao construir 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"
    isHistoryNavigation 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;
          });
        }
      }),
    );
  }

  // ...
});
    manter ativo Somente leitura. A configuração de manutenção de atividade 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 manterá a solicitação associada ativa se a página que a iniciou for descarregada antes que a solicitação seja concluída.
    • falso: o navegador não manterá a solicitação associada ativa se a página que a iniciou for descarregada antes que a solicitação seja concluída.

    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 (GET, POSTetc.)

    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 entre origens 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 de Compartilhamento de recursos de origem cruzada (CORS).
    • navegar: um modo para oferecer suporte à navegação. O valor de navegação deve ser usado somente pela navegação HTML. Uma solicitação de navegação é criada somente durante a navegação entre documentos.
    • no-cors: desabilita o CORS para solicitações entre origens. 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 entre origens. 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 do meio específico pelo qual ela foi iniciada. Por exemplo, quando um objeto de solicitação é criado usando o construtor Request(), o valor da propriedade de modo dessa solicitação é definido como cors. No entanto, para solicitações criadas por outros que não sejam Request() construtor, 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 de origem cruzada esteja presente, a solicitação é na maioria dos casos feita 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 tratados.
    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, client, no-referrerou um URL). Um valor de no-referrer 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
    política de referência Somente leitura. A política de referenciador que rege quais informações de referenciador são enviadas no cabeçalho de 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 Request a partir de uma 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 buscado. 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 Request, criando efetivamente uma cópia de um objeto Request existente. A estrutura do objeto é ditada pela classe Solicitação.
      Nota:
      Observe as seguintes atualizações de comportamento 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 será convertido para same-origin.
    opções Objeto Opcional. Um objeto Buscar RequestInit - com escopo, global que contém todas as 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 Request usando o construtor Request().

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

    O exemplo a seguir mostra como criar o novo objeto Request usando o parâmetro de entrada para recuperar um 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 Request 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 é resolvida com um arrayBuffer.

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

    Veja a seguir como criar uma nova solicitação usando o método arrayBuffer().

    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 é resolvida com um blob.

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

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

    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 é resolvida com um Uint8Array.

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

    Veja a seguir como criar uma nova solicitação usando o método bytes().

    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 Request atual.

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

    O exemplo a seguir demonstra como criar uma nova solicitação usando request() e copiá-la usando clone().

    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 é resolvida com um objeto FormData.

    O exemplo a seguir demonstra como criar uma nova solicitação usando request() e resolvê-la com o método formData() para resolvê-la 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 é resolvida para 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 request() e json() para analisar a solicitação e retorná-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 é resolvida 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 é resolvida com uma cadeia de caracteres no formato UTF-8.

    Este exemplo mostra como chamar text().

    var text = "Hello world";

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

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