Os gatilhos HTTP permitem invocar uma função do Function Compute por meio de requisições HTTP ou HTTPS padrão. Eles representam o caminho mais rápido para criar serviços web e APIs no Function Compute: sem sobrecarga de codificação, sem gateway adicional para gerenciar e compatíveis com qualquer ferramenta de teste HTTP ou serviço habilitado para webhook.
Como funciona
Um gatilho HTTP expõe sua função como um endpoint HTTP. Quando uma requisição chega, o Function Compute a autentica (se configurado), encaminha a requisição para sua função e retorna a resposta HTTP da função ao chamador.
Métodos HTTP suportados: GET, POST, PUT, DELETE, HEAD, PATCH e OPTIONS.
Exemplo de handler mínimo para função web em Node.js:
exports.handler = (event, context, callback) => {
const request = JSON.parse(event);
const response = {
statusCode: 200,
headers: { 'Content-Type': 'text/plain' },
body: 'Hello from Function Compute'
};
callback(null, response);
};
O objeto event contém a requisição HTTP completa (caminho, cabeçalhos, corpo e método). Retorne um objeto com statusCode, headers e body para enviar uma resposta HTTP.
Observações de uso
Antes de desenvolver com gatilhos HTTP, atente-se aos comportamentos descritos abaixo.
Risco de acesso anônimo
Se você definir o Authentication Method como No Authentication, qualquer pessoa com a URL do endpoint poderá invocar sua função. Para impor autorização personalizada, valide o cabeçalho Authorization no código da sua função. Para mais detalhes, consulte Configurar autenticação baseada em assinatura para gatilhos HTTP.
Restrição de download de APK
A partir de 10 de junho de 2024, gatilhos HTTP recém-criados bloqueiam downloads de arquivos APK (tipo MIME application/vnd.android.package-archive) em endpoints de rede pública. As requisições retornam o código de status HTTP 400. Para mais detalhes, consulte Como garantir que o endpoint público do seu gatilho HTTP retorne arquivos .apk corretamente.
Rotação de VIP
O Function Compute rotaciona periodicamente os endereços IP virtuais (VIPs) associados a endpoints públicos e privados. Codificar VIPs diretamente causa interrupções no serviço e não é coberto pelo acordo de nível de serviço (SLA) do Function Compute. Utilize um nome de domínio personalizado com configuração CNAME para garantir acesso estável. Para mais detalhes, consulte Configurar um nome de domínio personalizado.
Comportamento do domínio padrão e anexos
Ao utilizar o domínio padrão aliyuncs.com, o Function Compute adiciona content-disposition: attachment a todas as respostas, fazendo com que os navegadores baixem as respostas como arquivos em vez de renderizá-las. Configure um nome de domínio personalizado para remover esse comportamento.
Limitações
Limites do gatilho
É permitido no máximo um gatilho HTTP por versão ou alias de função. Consulte Gerenciamento de versões e Gerenciamento de aliases.
Os nomes de domínio integrados destinam-se apenas a testes — a estabilidade não é garantida. Não os utilize para serviços voltados à produção. Para serviços públicos, vincule um nome de domínio personalizado com registro ICP antes de expor sua função. Consulte Configurar um nome de domínio personalizado.
Limites de requisição
|
Limite |
Valor |
|
Tamanho do cabeçalho (todas as chaves + valores) |
8 KB |
|
Tamanho do caminho (incluindo parâmetros de consulta) |
4 KB |
|
Tamanho do corpo — invocação síncrona |
32 MB |
|
Tamanho do corpo — invocação assíncrona |
Exceder os limites de cabeçalho, caminho ou corpo para invocações síncronas retorna o código de status HTTP 400 com o código de erro InvalidArgument.
Cabeçalhos de requisição não suportados: qualquer cabeçalho que comece com x-fc-, além de connection e keep-alive.
Limites de resposta
|
Limite |
Valor |
|
Tamanho do cabeçalho (todas as chaves + valores) |
8 KB |
Exceder o limite de cabeçalho de resposta retorna o código de status HTTP 502 com o código de erro BadResponse.
Cabeçalhos de resposta não suportados: qualquer cabeçalho que comece com x-fc-, além de connection, content-length, date, keep-alive, server, upgrade e content-disposition:attachment.
Métodos de invocação
Invocação síncrona
Por padrão, os gatilhos HTTP utilizam invocação síncrona. A função processa a requisição e retorna o resultado antes que a conexão seja fechada. Consulte Invocação síncrona.
Invocação assíncrona
Na invocação assíncrona, o Function Compute persiste a requisição e retorna imediatamente o código de status HTTP 202, sem aguardar a conclusão da função. Qualquer código de status diferente de 202 indica falha na invocação. Consulte Mecanismo de nova tentativa para tratamento de falhas.
Existem duas formas de invocar assincronamente:
Assíncrono no nível da requisição: Adicione o cabeçalho
"X-Fc-Invocation-Type": "Async"a qualquer requisição HTTP. Consulte Invocação assíncrona.Tarefa assíncrona: Após configurar uma tarefa assíncrona para sua função, adicione o cabeçalho
"X-Fc-Async-Task-Id": "<task-id>"para especificar o ID da invocação. Consulte Tarefa assíncrona.
A resposta inclui o ID da requisição no cabeçalho, por exemplo: "X-Fc-Request-Id": "80bf7****281713e1". Para todos os cabeçalhos de requisição suportados, consulte Invocar uma função.
Autenticação e autorização
Chamadores externos devem passar pelas verificações de autenticação do Function Compute antes de acessar sua função por meio de um gatilho HTTP. Métodos suportados:
Compartilhamento de recursos de origem cruzada (CORS)
O Function Compute oferece três maneiras de lidar com requisições de compartilhamento de recursos de origem cruzada (CORS), cada uma com diferentes compensações em custo, complexidade e flexibilidade.
|
Recurso |
CORS configurado via API (recomendado) |
CORS padrão |
CORS definido pelo usuário (código) |
|
Requisição preflight faturada? |
Não faturada (o gateway a trata) |
Possíveis cobranças |
Faturada (função acionada) |
|
Alterações de código necessárias |
Nenhuma |
Nenhuma |
Muitas |
|
Versões de API suportadas |
Apenas FC 3.0 |
Todas as versões |
Todas as versões |
|
Complexidade de configuração |
Baixa (configuração única) |
Nenhuma |
Alta (é necessário tratar OPTIONS) |
Comportamento padrão do CORS
Por padrão, o Function Compute replica os cabeçalhos CORS com base na requisição. Para requisições simples (sem preflight), a resposta inclui:
Access-Control-Allow-Origin: copiado do cabeçalhoOriginda requisiçãoAccess-Control-Allow-Credentials:trueAccess-Control-Expose-Headers: cabeçalhos definidos pelo Function Compute
Tratar CORS no código da função
Para requisições simples, defina os cabeçalhos Access-Control-Allow-* diretamente na sua resposta.
Para requisições não simples, o navegador envia uma requisição OPTIONS preflight antes da requisição real. Adicione OPTIONS aos métodos permitidos do seu gatilho HTTP e trate-o no código da sua função.
<details> <summary>Exemplo em Node.js</summary>
exports.handler = (event, context, callback) => {
const method = JSON.parse(event).requestContext.http.method;
if (method === 'OPTIONS') {
const fcResponse = {
statusCode: 204,
headers: {
'Access-Control-Allow-Origin': 'http://www.fc.com',
'Access-Control-Allow-Methods': 'POST',
'Access-Control-Allow-Headers': 'Content-Type, Authorization',
'Access-Control-Max-Age': '3600'
},
body: ''
};
callback(null, fcResponse);
} else {
callback(null, {
statusCode: 200,
body: 'hello world'
});
}
};
</details>
<details> <summary>Exemplo em Python</summary>
import json
def handler(event, context):
evt = json.loads(event)
method = evt.get('requestContext', {}).get('http', {}).get('method', '')
if method == 'OPTIONS':
return {
'statusCode': 204,
'headers': {
'Access-Control-Allow-Origin': 'http://www.fc.com',
'Access-Control-Allow-Methods': 'POST',
'Access-Control-Allow-Headers': 'Content-Type, Authorization',
'Access-Control-Max-Age': '3600'
},
'body': ''
}
return {
'statusCode': 200,
'body': 'hello world'
}
</details>
<details> <summary>Exemplo em Go</summary>
package main
import (
"context"
"encoding/json"
)
type HttpRequest struct {
RequestContext struct {
Http struct {
Method string `json:"method"`
} `json:"http"`
} `json:"requestContext"`
}
type HttpResponse struct {
StatusCode int `json:"statusCode"`
Headers map[string]string `json:"headers"`
Body string `json:"body"`
}
func Handler(ctx context.Context, event []byte) (*HttpResponse, error) {
var req HttpRequest
if err := json.Unmarshal(event, &req); err != nil {
return nil, err
}
if req.RequestContext.Http.Method == "OPTIONS" {
return &HttpResponse{
StatusCode: 204,
Headers: map[string]string{
"Access-Control-Allow-Origin": "http://www.fc.com",
"Access-Control-Allow-Methods": "POST",
"Access-Control-Allow-Headers": "Content-Type, Authorization",
"Access-Control-Max-Age": "3600",
},
Body: "",
}, nil
}
return &HttpResponse{StatusCode: 200, Body: "hello world"}, nil
}
</details>
CORS configurado via API
O CORS configurado via API está disponível como prévia por convite. Para ativá-lo, entre em contato conosco e forneça o ID da sua conta Alibaba Cloud (UID).
O CORS configurado via API é um recurso da camada de gateway. Configure políticas de CORS diretamente em um gatilho HTTP ou nome de domínio personalizado — nenhuma lógica de CORS é necessária no código da sua função.
Principais benefícios:
Sem alterações de código: Desacople o tratamento de CORS da lógica de negócios.
Menor custo: O gateway trata as requisições
OPTIONSpreflight diretamente, sem executar nenhuma instância de função.Gerenciamento centralizado: Aplique políticas de CORS no nível do gatilho ou do domínio.
Menor latência: O gateway retorna respostas preflight sem invocar sua função.
Escopo:
Apenas funções FC 3.0 (versão da API
2023-03-30)Aplica-se a gatilhos HTTP (incluindo domínios de teste integrados) e nomes de domínio personalizados vinculados
Configure utilizando a API Atualizar gatilho ou Atualizar nome de domínio personalizado.
Parâmetros de configuração de CORS
|
Parâmetro |
Tipo |
Descrição |
Padrão |
Restrição |
|
|
Array |
Origens permitidas para acessar recursos |
— |
Máximo de 100 itens, cada um ≤ 256 caracteres. Suporta |
|
|
Array |
Métodos HTTP permitidos |
Métodos do gatilho |
Não inclua |
|
|
Array |
Cabeçalhos de requisição personalizados permitidos pelos navegadores |
— |
Máximo de 50 itens. Suporta |
|
|
Array |
Cabeçalhos de resposta expostos aos navegadores |
Padrão do sistema |
Máximo de 50 itens. |
|
|
Booleano |
Se deve permitir cookies e credenciais em requisições de origem cruzada |
|
Se |
|
|
Inteiro |
Duração do cache para respostas preflight, em segundos |
|
Intervalo: 0–86400. |
Valores para allowOrigins:
*: Permite todas as origens (apenas quandoallowCredentialséfalse).https://*: Permite todas as origens que começam comhttps://.Domínio específico:
https://example.com.Múltiplos domínios:
["https://example.com", "https://app.example.com"].Wildcards de subdomínio (por exemplo,
https://*.example.com) não são suportados. Liste todos os domínios explicitamente.
Valores para allowMethods:
Métodos HTTP padrão:
GET,POST,PUT,DELETE,PATCH,HEAD.*: Permite todos os métodos.Não inclua
OPTIONS— o gateway gerencia todas as requisições preflight automaticamente.
Como o gateway trata as requisições
Requisições preflight (OPTIONS)
O gateway valida os cabeçalhos Origin, Access-Control-Request-Method e Access-Control-Request-Headers:
Validação aprovada: Retorna
204 No Contentcom os cabeçalhos CORS configurados. Não invoca a função.-
Falha na validação:
A origem corresponde, mas outros cabeçalhos não: O gateway define cabeçalhos CORS básicos e encaminha a requisição para a função.
A origem não corresponde: Nenhum cabeçalho CORS é definido. A requisição é encaminhada para a função.
Requisições simples (GET, POST, HEAD, etc.)
O gateway valida apenas o cabeçalho Origin:
Validação aprovada: Injeta
Access-Control-Allow-Origine outros cabeçalhos CORS na resposta. Encaminha a requisição para a função.Falha na validação: Não injeta cabeçalhos CORS. Ainda assim, encaminha a requisição para a função.
Prioridade
Quando múltiplos métodos de tratamento de CORS se aplicam ao mesmo caminho, o gateway os aplica nesta ordem:
CORS configurado via API (maior prioridade): Se ativado, o gateway aplica esta configuração primeiro.
CORS padrão: Se o CORS configurado via API estiver desativado, o gateway usa o comportamento padrão integrado de replicação.
CORS definido pela função: Os cabeçalhos retornados pela sua função são mesclados com os resultados acima.
Gatilho HTTP vs. gatilho do API Gateway
Tanto os gatilhos HTTP quanto os gatilhos do API Gateway permitem a criação de aplicações web.
|
Gatilho HTTP |
Gatilho do API Gateway |
|
|
Mais indicado para |
Caminho leve e direto de HTTP para função |
Quando você precisa de recursos do API Gateway, como gerenciamento de tráfego ou transformação de requisições |
|
Roteamento de caminho |
Mapeie caminhos de URL para sua função vinculando um nome de domínio personalizado |
Configure o Function Compute como backend da API |
|
Documentação |
Os gatilhos HTTP oferecem estas vantagens em relação aos gatilhos do API Gateway:
Configuração mais rápida e depuração mais simples, sem necessidade de configuração adicional de gateway.
Sem sobrecarga de codificação ou decodificação JSON — os gatilhos HTTP passam requisições e respostas diretamente.
Compatíveis com ferramentas padrão de teste HTTP.
Integração fácil com serviços habilitados para webhook, como busca de origem CDN e Simple Message Queue (anteriormente MNS).
Perguntas frequentes
Por que minha chamada de API falha após adicionar OPTIONS a allowMethods?
Não adicione OPTIONS a corsConfig.allowMethods. O gateway gerencia todas as requisições preflight automaticamente. Incluir OPTIONS manualmente causa erros no tratamento de requisições.
Após configurar o CORS via API, requisições OPTIONS retornam 200 em vez de 204. Por quê?
Confirme se sua conta recebeu acesso à prévia por convite. Se o plugin do gateway não estiver totalmente ativado, o gateway reverte para o comportamento padrão de CORS, que retorna 200 e encaminha a requisição para sua função.
**Posso usar wildcards de subdomínio em allowOrigins, por exemplo *.example.com?**
Não. Wildcards de subdomínio não são suportados. Liste todos os domínios necessários explicitamente no array allowOrigins ou use https://* para correspondência ampla de origens HTTPS.
Meu código de função também define cabeçalhos CORS. Haverá conflitos?
Não. Cabeçalhos gerados pelo gateway e cabeçalhos retornados pela função são mesclados. Se existirem duplicatas, os navegadores usam o primeiro valor compatível. Aplicações existentes continuam funcionando durante a migração.