From 074785cea106179cb3305637055ab0a009ca74f2 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:42:52 -0500 Subject: initial commit --- .../web/api/fetch_api/basic_concepts/index.html | 66 +++++ files/pt-br/web/api/fetch_api/index.html | 85 ++++++ .../pt-br/web/api/fetch_api/using_fetch/index.html | 311 +++++++++++++++++++++ .../fetch_api/uso_de_busca_cross-global/index.html | 35 +++ 4 files changed, 497 insertions(+) create mode 100644 files/pt-br/web/api/fetch_api/basic_concepts/index.html create mode 100644 files/pt-br/web/api/fetch_api/index.html create mode 100644 files/pt-br/web/api/fetch_api/using_fetch/index.html create mode 100644 files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html (limited to 'files/pt-br/web/api/fetch_api') diff --git a/files/pt-br/web/api/fetch_api/basic_concepts/index.html b/files/pt-br/web/api/fetch_api/basic_concepts/index.html new file mode 100644 index 0000000000..c9845e75aa --- /dev/null +++ b/files/pt-br/web/api/fetch_api/basic_concepts/index.html @@ -0,0 +1,66 @@ +--- +title: Conceitos básicos de Fetch +slug: Web/API/Fetch_API/Basic_concepts +translation_of: Web/API/Fetch_API/Basic_concepts +--- +

{{DefaultAPISidebar("Fetch API")}}{{draft}}

+ +
+

A Fetch API fornece uma interface para buscar recursos (inclusive pela rede). Parecerá familiar para alguém que já tenha usado {{domxref("XMLHttpRequest")}}, mas ela fornece um conjunto de recursos mais poderoso e flexível . Este artigo expõe alguns conceitos básicos da API Fetch.

+
+ +
+

Este artigo será incrementado ao longo do tempo. Se você achar um conceito em Fetch que parece precisar de uma explicação melhor, informe alguém em fórum de discussãMDN, or Mozilla IRC (#mdn room.)

+
+ +

Em poucas palavras

+ +

O coração do Fetch são as abstrações da Interface do HTTP {{domxref("Request")}}, {{domxref("Response")}}, {{domxref("Headers")}}, e {{domxref("Body")}} payloads, juntamente com {{domxref("GlobalFetch.fetch","global fetch")}} método para iniciar requisições de recursos assíncronos. Como os componentes principais do HTTP são abstraidos como objetos de JavaScript, torna-se fácil APIs fazer uso das funcionalidades.

+ +

Service Workers é um exemplo de uma API que faz um grande uso de Fecth.

+ +

Fetch leva a assincronicidade um passo além. A API é completamente baseada em {{jsxref("Promise")}}.

+ +

Guard

+ +

Guard é uma novidade de objetos {{domxref("Headers")}}, podendo assumir os valores de immutable, request, request-no-cors, response, ou none, dependendo de onde o cabeçalho é utilizado.

+ +

Quando um novo objeto {{domxref("Headers")}} é criado usando o {{domxref("Headers.Headers","Headers()")}} {{glossary("constructor")}}, seu guard é configurado como none (o padrão). Quando um objeto {{domxref("Request")}} ou {{domxref("Response")}} é criado, tem um objeto {{domxref("Headers")}}  associado cujo guard é resumido a seguir:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Novo tipo de objetoConstrutor criadoConfiguração guard associada ao objeto {{domxref("Headers")}}
{{domxref("Request")}}{{domxref("Request.Request","Request()")}}request
{{domxref("Request.Request","Request()")}} com {{domxref("Request.mode","mode")}} de no-corsrequest-no-cors
{{domxref("Response")}}{{domxref("Response.Response","Response()")}}response
Métodos {{domxref("Response.error","error()")}} ou {{domxref("Response.redirect","redirect()")}}immutable
+ +

Um cabeçalho guard afeta os métodos {{domxref("Headers.set","set()")}}, {{domxref("Headers.delete","delete()")}}, e {{domxref("Headers.append","append()")}} os quais mudam o conteúdo do cabeçalho. UmTypeError é lançado se você tentar modificar um objeto {{domxref("Headers")}} objeto cujo "guard" é immutable. De qualquer maneira, a operação vai funcionar se

+ + diff --git a/files/pt-br/web/api/fetch_api/index.html b/files/pt-br/web/api/fetch_api/index.html new file mode 100644 index 0000000000..6409994ae7 --- /dev/null +++ b/files/pt-br/web/api/fetch_api/index.html @@ -0,0 +1,85 @@ +--- +title: Fetch API +slug: Web/API/Fetch_API +tags: + - API + - Experimental + - Fetch + - Referência(2) + - XMLHttpRequest + - request +translation_of: Web/API/Fetch_API +--- +

{{DefaultAPISidebar("Fetch API")}}{{ SeeCompatTable() }}

+ +

A Fetch API fornece uma interface para buscar recursos (por exemplo, em toda a rede). Parecerá familiar para qualquer pessoa que tenha usado XMLHttpRequest, porém a nova API oferece um conjunto de recursos mais poderoso e flexível.

+ +

Conceitos e uso

+ +

O Fetch fornece uma definição genérica de objetos de {{domxref("Request")}} e {{domxref("Response")}}  (e outras coisas envolvidas com solicitações de rede). Isso permitirá que eles sejam usados onde quer que sejam necessários no futuro, seja para service workers, Cache API e outras coisas similares que manipulam ou modifiquem pedidos e respostas ou qualquer tipo de caso de uso que possa exigir que você gere suas próprias responses programaticamente.

+ +

Ele também fornece uma definição para conceitos relacionados como CORS e a semântica de cabeçalho de origem HTTP, suplantando suas definições separadas em outro lugar.

+ +

Para fazer uma solicitação e buscar um recurso, use o método {{domxref("GlobalFetch.fetch")}} . Ele é implementado em várias interfaces, especificamente {{domxref("Window")}} e {{domxref("WorkerGlobalScope")}}. Isso torna disponível em praticamente qualquer contexto em que você possa querer obter recursos.

+ +

O método fetch () tem um argumento obrigatório, o caminho para o recurso que deseja obter. Ele retorna uma promessa que resolve a {{domxref("Response")}} para esta requisição, seja ele bem-sucedido ou não. Você também pode, opcionalmente, passar um objeto de opções de inicialização como o segundo argumento (consulte {{domxref("Request")}}).

+ +

Uma vez que uma {{domxref("Response")}} é recuperada, há uma série de métodos disponíveis para definir o conteúdo do corpo e como ele deve ser tratado (veja {{domxref("Body")}}.)

+ +


+ Você pode criar um pedido e uma resposta diretamente usando os construtores {{domxref("Request.Request","Request()")}} e {{domxref("Response.Response","Response()")}}, mas é improvável que você faça isso diretamente. Em vez disso, é mais provável que sejam criados como resultados de outras ações da API (por exemplo,  {{domxref("FetchEvent.respondWith")}} de service workers).

+ +
+

Note: Encontre mais informações sobre os recursos do Fetch API em Using Fetch,  e conceitos para estudos em Fetch basic concepts.

+
+ +

Fetch Interfaces

+ +
+
{{domxref("GlobalFetch")}}
+
Contém o método fetch() usado para buscar um recurso.
+
{{domxref("Headers")}}
+
Representa cabeçalhos response/request, permitindo que você os consulte e faça diferentes ações dependendo dos resultados.
+
{{domxref("Request")}}
+
Representa um pedido de recursos.
+
{{domxref("Response")}}
+
Representa a resposta de uma requisição.
+
+ +

Fetch mixin

+ +
+
{{domxref("Body")}}
+
Providencia métodos relacionados ao corpo da resposta/requisição, permitindo que você declare qual seu tipo de conteúdo e como ele deve ser tratado.
+
+ +

Especificações

+ + + + + + + + + + + + + + +
EspecificaçãoStatusComentários
{{SpecName('Fetch')}}{{Spec2('Fetch')}}Definição inicial
+ + + +

{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}

+ +

Veja também

+ + diff --git a/files/pt-br/web/api/fetch_api/using_fetch/index.html b/files/pt-br/web/api/fetch_api/using_fetch/index.html new file mode 100644 index 0000000000..0b951f7461 --- /dev/null +++ b/files/pt-br/web/api/fetch_api/using_fetch/index.html @@ -0,0 +1,311 @@ +--- +title: Usando Fetch +slug: Web/API/Fetch_API/Using_Fetch +translation_of: Web/API/Fetch_API/Using_Fetch +--- +
+

A API Fetch fornece uma interface JavaScript para acessar e manipular partes do pipeline HTTP, tais como os pedidos e respostas. Ela também fornece o método global {{domxref("GlobalFetch.fetch","fetch()")}} que fornece uma maneira fácil e lógica para buscar recursos de forma assíncrona através da rede.

+
+ +

Este tipo de funcionalidade era obtida anteriormente utilizando {{domxref("XMLHttpRequest")}}. Fetch fornece uma alternativa melhor que pode ser facilmente utilizada por outras tecnologias como {{domxref("ServiceWorker_API", "Service Workers")}}. Fetch também provê um lugar lógico único para definir outros conceitos relacionados ao protocolo HTTP como CORS e extensões ao HTTP.

+ +

Note que a especificação fetch() difere de jQuery.ajax(), principalmente, de três formas:

+ + + +

Situação do suporte por navegadores

+ +

Os suportes para Fetch ainda estão em uma fase bastante precoce, mas começa a ter progresso. Se tornou um padrão no Firefox 39 e Chrome 42 até as versões mais atuais.

+ +

Caso tenha interesse no uso da ferramenta, há também uma Fetch Polyfill disponivel que recria as funcionalidade para outros navegadores que ainda não o suporta. Fique ciente que está em estado experimental e ainda não há uma versão completa.

+ +
+

Nota: There have been some concerns raised that the Fetch spec is at odds with the Streams spec; however, future plans show an intention to integrate Streams with Fetch: read Fetch API integrated with Streams for more information.

+
+ +

Detecção de Recursos

+ +

Fetch API support pode ser detectada na existência do escopo {{domxref("Headers")}}, {{domxref("Request")}}, {{domxref("Response")}} ou {{domxref("GlobalFetch.fetch","fetch()")}} no {{domxref("Window")}} ou {{domxref("Worker")}} . Por exemplo, faça o seguinte teste no seu código:

+ +
if(self.fetch) {
+    // execute minha solicitação do fetch aqui
+} else {
+    // faça alguma coisa com XMLHttpRequest?
+}
+ +

Fazendo as requisições Fetch

+ +

Uma requisição fetch é realizada para configuração. Temos um exemplo no seguinte código:

+ +
var myImage = document.querySelector('img');
+
+fetch('flowers.jpg')
+.then(function(response) {
+  return response.blob();
+})
+.then(function(myBlob) {
+  var objectURL = URL.createObjectURL(myBlob);
+  myImage.src = objectURL;
+});
+
+
+ +

Aqui estamos procurando uma imagem e inserindo em um elemento {{htmlelement("img")}}. O uso mais básico dofetch() acarreta em um argumento — a pasta do recurso que você deseja buscar — e retorna uma promessa contendo a resposta (a {{domxref("Response")}} object).

+ +

Esta é apenas uma resposta HTTP, não a imagem em sí. Para extrairmos a imagem da resposta, nós usamos o método {{domxref("Body.blob","blob()")}} (definido no mixin do {{domxref("Body")}}, que são implementados por ambos os objetos {{domxref("Request")}} e {{domxref("Response")}}.)

+ +
+

Nota: O Body mixin além disso possui métodos similares para extrair outros tipos de conteúdo do body; Veja a sessão {{anch("Body")}} para mais detalhes.

+
+ +

Um objectURL é criado na extração de {{domxref("Blob")}}, que então é inserido no {{domxref("img")}}.

+ +

Requisições Fetch são controladas pela directiva connect-src do Content Security Policy ao invés da directiva do recurso retornado.

+ +

Fornecendo opções de request

+ +

O método fetch() pode receber um segundo parametro opcional, que consiste em um objeto init que permite setar várias configurações:

+ +
var myHeaders = new Headers();
+
+var myInit = { method: 'GET',
+               headers: myHeaders,
+               mode: 'cors',
+               cache: 'default' };
+
+fetch('flowers.jpg',myInit)
+.then(function(response) {
+  return response.blob();
+})
+.then(function(myBlob) {
+  var objectURL = URL.createObjectURL(myBlob);
+  myImage.src = objectURL;
+});
+
+
+ +

See {{domxref("GlobalFetch.fetch","fetch()")}} for the full options available, and more descriptions.

+ +

Verificando se o fetch foi bem sucedido

+ +

Uma promise {{domxref("GlobalFetch.fetch","fetch()")}} será rejeitada com um {{jsxref("TypeError")}} quando um erro de rede é encontrado, embora isso geralmente signifique problemas de permissão ou similar — um 404 não constitui um erro de rede, por exemplo. Uma verificação precisa de um fetch()  bem-sucedido incluiria a verificação de que a promessa foi resolvida e, em seguida, a verificação de que a propriedade {{domxref("Response.ok")}} tem o valor de true. O código seria parecido com o abaixo:

+ +
fetch('flowers.jpg').then(function(response) {
+  if(response.ok) {
+    response.blob().then(function(myBlob) {
+      var objectURL = URL.createObjectURL(myBlob);
+      myImage.src = objectURL;
+    });
+  } else {
+    console.log('Network response was not ok.');
+  }
+})
+.catch(function(error) {
+  console.log('There has been a problem with your fetch operation: ' + error.message);
+});
+ +

Fornecendo seu próprio objeto de solicitação

+ +

Em vez de passar um caminho, para o recurso que você deseja solicitar, dentro da rquisição fetch(), você pode criar um objeto de solicitação usando o construtor {{domxref("Request.Request","Request()")}}, e então passar a solicitação como um argumento do método fetch() :

+ +
var myHeaders = new Headers();
+
+var myInit = { method: 'GET',
+               headers: myHeaders,
+               mode: 'cors',
+               cache: 'default' };
+
+var myRequest = new Request('flowers.jpg', myInit);
+
+fetch(myRequest)
+.then(function(response) {
+  return response.blob();
+})
+.then(function(myBlob) {
+  var objectURL = URL.createObjectURL(myBlob);
+  myImage.src = objectURL;
+});
+ +

Request() aceita exatamente os mesmos parâmetros do método fetch(). Você pode até mesmo passar um objeto de solicitação existente para criar uma cópia dele:​​​​​​

+ +
var anotherRequest = new Request(myRequest,myInit);
+ +

Isso é muito útil, pois os conteúdos de cada solicitação e resposta tem apenas um uso. Fazer uma cópia como essa permite que você use a solicitação / resposta novamente, variando as opções de inicialização, se desejar.

+ +
+

Nota: Também existe um método que cria uma cópia: {{domxref ("Request.clone", "clone ()")}}. Isso tem uma semântica ligeiramente diferente do outro método de cópia: o primeiro dirá se o conteúdo, da solicitação anterior, já tiver sido lido (ou copiado), enquanto o segundo, clone() não.

+
+ +

Headers

+ +

A interface {{domxref("Headers")}} permite que você crie seus proprios objetos headers por meio do construtor {{domxref("Headers.Headers","Headers()")}}. Um objeto headers é um  mapa multidimensional simples de nomes para o valor? 

+ +
var content = "Hello World";
+var myHeaders = new Headers();
+myHeaders.append("Content-Type", "text/plain");
+myHeaders.append("Content-Length", content.length.toString());
+myHeaders.append("X-Custom-Header", "ProcessThisImmediately");
+ +

O mesmo pode ser feito passando um array de arrays ou um objeto literal para o construtor:

+ +
myHeaders = new Headers({
+  "Content-Type": "text/plain",
+  "Content-Length": content.length.toString(),
+  "X-Custom-Header": "ProcessThisImmediately",
+});
+ +

O conteúdo pode ser consultado e recuperado:

+ +
console.log(myHeaders.has("Content-Type")); // true
+console.log(myHeaders.has("Set-Cookie")); // false
+myHeaders.set("Content-Type", "text/html");
+myHeaders.append("X-Custom-Header", "AnotherValue");
+
+console.log(myHeaders.get("Content-Length")); // 11
+console.log(myHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"]
+
+myHeaders.delete("X-Custom-Header");
+console.log(myHeaders.getAll("X-Custom-Header")); // [ ]
+ +

Some of these operations are only useful in {{domxref("ServiceWorker_API","ServiceWorkers")}}, but they provide a much nicer API for manipulating headers.

+ +

All of the Headers methods throw a TypeError if a header name is used that is not a valid HTTP Header name. The mutation operations will throw a TypeError if there is an immutable guard (see below). Otherwise they fail silently. For example:

+ +
var myResponse = Response.error();
+try {
+  myResponse.headers.set("Origin", "http://mybank.com");
+} catch(e) {
+  console.log("Cannot pretend to be a bank!");
+}
+ +

A good use case for headers is checking whether the content type is correct before you process it further. For example:

+ +
fetch(myRequest).then(function(response) {
+  var contentType = response.headers.get("content-type");
+  if(contentType && contentType.indexOf("application/json") !== -1) {
+    return response.json().then(function(json) {
+      // process your JSON further
+    });
+  } else {
+    console.log("Oops, we haven't got JSON!");
+  }
+});
+ +

Guard

+ +

Since headers can be sent in requests and received in responses, and have various limitations about what information can and should be mutable, headers objects have a guard property. This is not exposed to the Web, but it affects which mutation operations are allowed on the headers object.

+ +

Possible guard values are:

+ + + +
+

Note: You may not append or set a request guarded Headers’ Content-Length header. Similarly, inserting Set-Cookie into a response header is not allowed: ServiceWorkers are not allowed to set cookies via synthesized responses.

+
+ +

Response objects

+ +

As you have seen above, {{domxref("Response")}} instances are returned when fetch() promises are resolved.

+ +

They can also be created programmatically via JavaScript, but this is only really useful in {{domxref("ServiceWorker_API", "ServiceWorkers")}}, when you are providing a custom response to a received request using a {{domxref("FetchEvent.respondWith","respondWith()")}} method:

+ +
var myBody = new Blob();
+
+addEventListener('fetch', function(event) {
+  event.respondWith(
+    new Response(myBody, {
+      headers: { "Content-Type" : "text/plain" }
+    })
+  );
+});
+ +

The {{domxref("Response.Response","Response()")}} constructor takes two optional arguments — a body for the response, and an init object (similar to the one that {{domxref("Request.Request","Request()")}} accepts.)

+ +

The most common response properties you'll use are:

+ + + +
+

Note: The static method {{domxref("Response.error","error()")}} simply returns an error response. Similarly, {{domxref("Response.redirect","redirect()")}} returns a response resulting in
+ a redirect to a specified URL. These are also only relevant to Service Workers.

+
+ +

Body

+ +

Both requests and responses may contain body data. A body is an instance of any of the following types.

+ + + +

The {{domxref("Body")}} mixin defines the following methods to extract a body (implemented by both {{domxref("Request")}} and {{domxref("Response")}}). These all return a promise that is eventually resolved with the actual content.

+ + + +

This makes usage of non-textual data much easier than it was with XHR.

+ +

Request bodies can be set by passing body parameters:

+ +
var form = new FormData(document.getElementById('login-form'));
+fetch("/login", {
+  method: "POST",
+  body: form
+});
+ +

Both request and response (and by extension the fetch() function), will try to intelligently determine the content type. A request will also automatically set a Content-Type header if none is set in the dictionary.

+ +

Especificações

+ + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('Fetch')}}{{Spec2('Fetch')}}Initial definition
+ +

Compatibilidade com os browsers

+ +

{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}

+ +
+ + diff --git a/files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html b/files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html new file mode 100644 index 0000000000..c569966b5a --- /dev/null +++ b/files/pt-br/web/api/fetch_api/uso_de_busca_cross-global/index.html @@ -0,0 +1,35 @@ +--- +title: Uso de busca Cross-global +slug: Web/API/Fetch_API/Uso_de_busca_Cross-global +translation_of: Web/API/Fetch_API/Cross-global_fetch_usage +--- +

 

+ +

Este artigo explica um "edge case" (um problema ou situação que ocorre apenas em um parâmetro operacional extremo) que ocorre ao utilizar fetch (e potencialmente outras APIs que exibem o mesmo tipo de comportamento de recuperação de recurso). Quando uma busca de cross-origin envolvendo uma URL relativa é iniciada a partir de um {{htmlelement ("iframe")}}, a URL relativa costumava ser resolvida na localização global atual, em vez da localização do iframe.

+ +

O "edge case"

+ +

Muitos sites nunca se deparam com este caso extremo. Para que isso aconteça:

+ + + +

O problema

+ +

No passado, resolveríamos o URL relativo contra o global atual, por exemplo:

+ +
let absolute = new URL(relative, window.location.href)
+ +

Isto não é um problema como tal. É que diferentes APIs que exibem esse tipo de comportamento estavam fazendo isso de maneira inconsistente com o comportamento definido na especificação, o que poderia levar a problemas mais adiante.

+ +

A solução

+ +

No Firefox 60 em diante, o Mozilla resolve a URL relativa contra o global que possui a função fetch() que está sendo usada (veja {{bug (1432272)}}). Portanto, no caso descrito acima, ele é resolvido em relação à localização do iframe:

+ +
let absolute = new URL(relative, frame.contentWindow.location.href)
+ +

Há muita discussão em andamento sobre a obtenção de novas especificações para se alinhar a essa mudança de comportamento, a fim de mitigar possíveis problemas no futuro.

-- cgit v1.2.3-54-g00ecf