Todos os produtos
Search
Central de documentação

Function Compute:Visão geral do gatilho HTTP

Última atualização: Jun 29, 2026

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

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

Consulte Limites de recursos de execução de funções

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çalho Origin da requisição

  • Access-Control-Allow-Credentials: true

  • Access-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 OPTIONS preflight 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

allowOrigins

Array

Origens permitidas para acessar recursos

Máximo de 100 itens, cada um ≤ 256 caracteres. Suporta * ou https://*.

allowMethods

Array

Métodos HTTP permitidos

Métodos do gatilho

Não inclua OPTIONS — o gateway trata o preflight automaticamente.

allowHeaders

Array

Cabeçalhos de requisição personalizados permitidos pelos navegadores

Máximo de 50 itens. Suporta *.

exposeHeaders

Array

Cabeçalhos de resposta expostos aos navegadores

Padrão do sistema

Máximo de 50 itens.

allowCredentials

Booleano

Se deve permitir cookies e credenciais em requisições de origem cruzada

false

Se true, allowOrigins não pode ser *.

maxAge

Inteiro

Duração do cache para respostas preflight, em segundos

3600

Intervalo: 0–86400.

Valores para allowOrigins:

  • *: Permite todas as origens (apenas quando allowCredentials é false).

  • https://*: Permite todas as origens que começam com https://.

  • 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 Content com 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-Origin e 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:

  1. CORS configurado via API (maior prioridade): Se ativado, o gateway aplica esta configuração primeiro.

  2. CORS padrão: Se o CORS configurado via API estiver desativado, o gateway usa o comportamento padrão integrado de replicação.

  3. 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

Configurar um nome de domínio personalizado

Usar o Function Compute como serviço de backend de API

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

Onde configuro a porta de escuta?

Configure a porta de escuta apenas ao criar a função como uma Web Function.

Minha função está demorando muito. Como resolver?

A causa depende do padrão observado:

Minha função retorna o código de status HTTP 499. Como lidar com isso?

Um código 499 significa que o cliente fechou a conexão antes que a função respondesse. Após um erro 499, a instância da função reinicia — configure verificações de integridade para evitar reinicializações desnecessárias. Consulte Por que a instância da função reinicia após um erro 499 do cliente?

Se timeouts no lado do cliente forem a causa raiz, mova a lógica que consome tempo para uma função separada e invoque-a assincronamente, ou mude para invocação assíncrona no lado do cliente.

Atualizei a configuração da minha função. Quando ela entra em vigor?

As atualizações de configuração entram em vigor após a conclusão da execução atual. Requisições já em andamento usam a configuração antiga até terminarem; novas requisições usam a configuração atualizada.

Alternativamente, exclua a função atual e crie uma nova com a configuração atualizada.

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.