ESA Fetch API - Edge Functions - Edge Security Acceleration: Central de Documentação do Alibaba Cloud

Busque dados em POPs de borda via HTTP ou HTTPS. A Fetch API funciona de maneira semelhante à Fetch API do navegador e oferece suporte a carregamento dinâmico de conteúdo, interação com backend e testes A/B.

Definição do método

O Fetch é totalmente assíncrono e não bloqueia a execução do script, a menos que você utilize await. O sistema aceita até quatro sub-requisições simultâneas e gerencia as conexões persistentes internamente.

O Fetch aceita requisições HTTP e HTTPS. Cada redirect conta como uma sub-requisição, com limite máximo de 12 operações de redirect por requisição.

Definição do método

fetch(arg, init). Este método segue a especificação MDN WorkerOrGlobalScope.fetch().
Limites do método
- A Fetch API aceita apenas nomes de domínio, não endereços IP. Portas padrão: 80 (HTTP) e 443 (HTTPS).
- As propriedades credentials, referrer, referrerPolicy, cache e integrity do parâmetro init não têm efeito.
- O valor padrão de redirect é follow, que segue respostas 3xx da origem. Defina redirect como manual para desativar o seguimento de redirecionamentos.
Nota
- Os modos de Fetch específicos do navegador não se aplicam. Em CDN, DCDN ou ESA, o CROS fetch pode recuperar dados de qualquer origem.
- Para enviar quatro ou mais sub-requisições, envie um ticket para solicitar aumento de cota.
- O comprimento total da URL de requisição não pode exceder 4 KB.
- Recursos buscados com compressão gzip são descompactados por padrão. Adicione o parâmetro manual para desativar a descompressão. A seção Descompressão aborda os detalhes.

Definir período de tempo limite

Função de tempo limite

/**
 * Request timeout control implementation
 *
 * @param {Number} timeout Timeout period, in ms
 * @param {Object} config Timeout configuration
 *   - @param {Object|Funtion} handler Value to return on timeout
 * @returns
 */
const RequestTimeout = (timeout, config) => {
  return new Promise((resolve) => {
    const { handler = null } = config;
    let timer = setTimeout(() => {
      clearTimeout(timer);
      timer = null;

      const defaultRes = (typeof handler === 'function' ? handler() : handler) || {};
      resolve(defaultRes);
    }, timeout);
  });
};

Exemplo de chamada

const KV_TIMEOUT = 1000;
let edgekv = new EdgeKV({
  namespace: KV_NS,
});

let kvRequest = edgekv.get(key, getType);
let timeoutPromise = RequestTimeout(KV_TIMEOUT, {
  handler: {
    res: {},
    errorMessage: `kv request timeout (${KV_TIMEOUT}ms)`,
  }
});

let resp = await Promise.race([
  kvRequest,
  timeoutPromise,
]);

if (resp === undefined) {
  return "kv not found, key = " + key;
} else {
  return resp;
}

Redirecionamento

O Fetch segue redirecionamentos 3xx (301, 302, 303, 307, 308). Especifique um dos três comportamentos de redirecionamento:

{redirect: "manual"}: Não segue redirecionamentos 3xx. Gerencie os redirecionamentos manualmente.
{redirect: "error"}: Gera erro para respostas 3xx.
{redirect: "follow"}: (Padrão) Segue redirecionamentos 3xx. Limite máximo de 20 redirecionamentos.

Comportamento de redirecionamento por código de status:

Código de status	Detalhes do redirecionamento
301, 302, 303, 308	O método da requisição muda para GET e o corpo é ignorado.
307	Apenas métodos GET são seguidos. Outros métodos geram erro.

Nota

Os redirecionamentos utilizam o cabeçalho Location, que é obrigatório. A ausência desse cabeçalho causa erro.

O cabeçalho Location pode conter uma lista de URLs separadas por vírgulas (,). Apenas a primeira URL é utilizada; as demais são ignoradas.
O cabeçalho Location pode conter uma URL absoluta ou relativa.

Descompressão

A Fetch API permite configurar um modo de descompressão, como fetch("https://www.example.com",{decompress: "manual"}). O parâmetro decompress aceita os seguintes valores:

manual: não descompacta os dados. Se o servidor retornar dados compactados em uma requisição fetch, os dados recebidos pelo EdgeRoutine (ER) também estarão compactados.
decompress: descompacta os dados automaticamente. Este é o valor padrão. A Fetch API suporta compressão Gzip. O ER detecta ou descompacta os dados automaticamente com base no cabeçalho Content-Encoding. Após a descompressão, o ER altera o valor de Content-Encoding. Caso o parâmetro Gzip seja removido, configure as opções abaixo para evitar exceções durante a transmissão de dados:
- content-encoding: gzip: O ER reconhece o valor de Content-Encoding e descompacta os dados.
- content-encoding: gzip, identity: O ER reconhece o valor de Content-Encoding e descompacta os dados.
Nota
Algoritmos diferentes de Gzip causam exceções.
fallbackIdentity: O efeito deste valor assemelha-se ao do valor decompress. Se o ER não reconhecer este valor, ele não descompactará os dados.

Importante

Após a descompressão automática dos dados pela Fetch API, não é possível transmitir o cabeçalho Content-Length conforme necessário se a resposta já contiver esse cabeçalho. Isso ocorre porque o Content-Length indica o tamanho dos dados antes da descompressão.

content-length

Quando content-length está definido, o Fetch envia o corpo usando codificação content-length. Sem content-length, o Fetch envia todos os dados do corpo usando codificação chunked.

Configurações de content-length
- Se content-length for um número não negativo: O Fetch lê e envia o número especificado de bytes do fluxo do corpo. Os dados são enviados usando codificação content-length. Se content-length for 0, nenhum dado será enviado.
- Se content-length for um valor inválido: O Fetch envia todos os dados do corpo usando codificação chunked.
Exemplo

O Fetch descompacta o conteúdo automaticamente. O cabeçalho content-length da resposta ainda reflete o tamanho anterior à descompressão. Se você modificar o corpo antes do encaminhamento, verifique se content-length corresponde ao tamanho real do corpo. Uma incompatibilidade em content-length causa entrega incorreta de conteúdo.
Neste exemplo, um cliente envia uma requisição POST com um cabeçalho content-length. Se você criar uma nova requisição Fetch reutilizando os cabeçalhos do cliente, o content-length pode não corresponder ao novo tamanho do corpo. Sempre verifique o tamanho do corpo ao repassar cabeçalhos.
```
export default {
  fetch(request) {
    return handleRequest(request)
  }
}
async function handleRequest(request) {
  return fetch("http://www.example.com", {
    headers: request.headers,
    method: request.method,
    body: "SomeData"
  });
}
```

Headers

Definição

Para obter mais informações sobre o objeto Headers, consulte Headers.
Limites

Um cabeçalho registra a quantidade de recursos de memória consumidos. O tamanho máximo de um objeto Headers é 8 KB. Se o tamanho exceder esse limite, o sistema gera uma exceção JavaScript.
Lista de bloqueios
A Fetch API utiliza uma lista de bloqueios de cabeçalhos. Tentativas de leitura ou gravação de um cabeçalho presente nessa lista geram exceção. A tabela a seguir descreve os cabeçalhos incluídos na lista de bloqueios.
- expect
- te
- trailer
- upgrade
- proxy-connection
- connection
- keep-alive
- dnt
- host
- Cabeçalhos reservados

Request

Definição

Segue a especificação MDN Request.
Limites
As seguintes propriedades de Request não são suportadas em CDN, DCDN ou ESA.
- context
- credentials
- destination
- integrity
- mode
- referrer
- referrerPolicy
- cache
Usos comuns
- Obter o método da requisição: request.method.
- Obter a URL da requisição: request.url.
- Obter os cabeçalhos da requisição: request.headers.
- Obter o payload da requisição: request.body. O corpo é um objeto ReadableStream.
- Obter JSON: await request.json().
- Obter dados de formulário: await request.formData().
- Obter uma string UTF-8: await request.text().
Como extensão não padrão, request.ignore drena o fluxo do corpo no nível do socket sem carregá-lo na memória da VM JavaScript, evitando atrasos de GC. Chame await request.ignore() quando não precisar do corpo da requisição. O runtime devolve a conexão ao pool após a leitura completa do corpo.

Response

Definição

Segue a especificação MDN Response.
Limites

As propriedades useFinalURLS e error não são suportadas em CDN, DCDN ou ESA.
Usos comuns
- Obter o código de resposta: response.status.
- Obter a frase de motivo da resposta: response.statusText.
- Obter os cabeçalhos da resposta: response.headers.
- Obter a URL da resposta: response.url. Esta é a URL final após todos os redirecionamentos.
- Obter todas as URLs de redirecionamento (não padrão): response.urlList. Response implementa um mixin de corpo semelhante ao Request; portanto, aplicam-se os mesmos métodos de recuperação de corpo.

FormData

Definição

Para obter mais informações sobre a operação FormData, consulte FormData.
Limites

A operação FormData assemelha-se à operação Headers. O FormData limita o tamanho dos cabeçalhos. Se o tamanho de um cabeçalho exceder o limite superior, o sistema gera uma exceção. Ao enviar FormData como corpo de uma requisição HTTP, content-type assume o valor form-data/multipart por padrão.

URLSearchParams

Definição

Para obter mais informações sobre a operação URLSearchParams, consulte URLSearchParams().
Limites

Ao enviar URLSearchParams como corpo de uma requisição HTTP, content-type assume o valor application/x-www-form-urlencode por padrão. O tamanho dos dados não pode exceder 1.000 bytes.

Blob e File

Definição
- Para obter mais informações sobre a operação Blob, consulte Blob.
- Para obter mais informações sobre a operação File, consulte File.
Limites

O ER suporta as classes Blob e File, que atendem aos padrões das operações Blob e File. O ER não pode ler ou gravar arquivos. Passe as classes Blob e File suportadas pelo ER para o corpo da resposta. O valor do cabeçalho content-type corresponde ao tipo MIME na operação Blob ou File.