O Function Compute aceita o API Gateway como origem de eventos. Ao configurar o Function Compute como serviço de back-end de uma API, o API Gateway encaminha as requisições recebidas para a função associada e retorna o resultado da execução ao chamador.
Quando usar gatilhos do API Gateway
Tanto os gatilhos do API Gateway quanto os gatilhos HTTP expõem funções como endpoints HTTP. Escolha a opção adequada conforme seus requisitos:
|
Capacidade |
Gatilho do API Gateway |
Gatilho HTTP |
|
Listas de permissões e bloqueios de IP |
Suportado |
Não suportado |
|
Autenticação (AppKey, AppCode) |
Suportado |
Não suportado |
|
Modelagem de tráfego |
Suportado |
Não suportado |
|
Transformação de dados |
Suportado |
Não suportado |
Use um gatilho do API Gateway quando precisar de controle de acesso avançado, autenticação ou gerenciamento de tráfego. Para exposição HTTP simples, um gatilho HTTP é suficiente.
O API Gateway suporta funções de evento e funções web como back-end. O modelo de integração difere entre eles:
Função de evento: O API Gateway converte a requisição HTTP em um evento JSON estruturado e o transmite à sua função. A função deve retornar uma resposta JSON em um formato específico.
Função web: O API Gateway encaminha a requisição HTTP bruta para o endpoint de rede interna da sua função. A função processa a requisição diretamente como um servidor HTTP.
Conectar uma função de evento ao API Gateway
Pré-requisitos
Antes de começar, verifique se você tem:
Uma conta Alibaba Cloud com acesso ao Function Compute e ao API Gateway
Uma região selecionada para ambos os serviços (coloque-os na mesma região para evitar taxas de tráfego de rede pública)
Etapa 1: Criar uma função de evento
Crie uma função de evento no console do Function Compute 3.0. Para mais informações, consulte Criar uma função de evento.
Etapa 2: Criar um serviço de back-end do API Gateway
Defina um serviço de back-end no API Gateway e vincule-o à sua função.
-
Faça login no console do API Gateway, selecione uma região e, no painel de navegação à esquerda, escolha Manage APIs > Backend Services. No canto superior direito, clique em Create Backend Service. Configure as informações necessárias e clique em Confirm.

-
Na página Backend Services, clique no serviço de back-end recém-criado. Clique na aba Production. Na seção Basic Information, clique em Create, selecione a função de evento da Etapa 1 e clique em Publish.

Etapa 3: Criar e publicar uma API
-
No console do API Gateway, crie um grupo de APIs. Coloque o grupo na mesma região da sua função.
Se o grupo de APIs e a função estiverem em regiões diferentes, o API Gateway acessará o Function Compute pela rede pública, gerando taxas de tráfego. Para menor latência e melhor segurança dos dados, use a mesma região.
-
Crie e publique uma API com as seguintes configurações principais. Mantenha os padrões para todos os outros campos.
Item de configuração
Valor
Security authentication
No authentication
Configuration mode
Use an existing backend service
Backend service type
Function Compute
Version
Function Compute 3.0
Function type
Event function
Backend services
Selecione o serviço de back-end criado na Etapa 2

Etapa 4: Escrever o código da função
Faça login no console do Function Compute. No painel de navegação à esquerda, clique em Functions.
Na barra de navegação superior, selecione a região. Na página Functions, clique na função que deseja gerenciar.
Na página de detalhes da função, clique na aba Code. Escreva seu código no editor e clique em Deploy.
Todos os exemplos leem o evento de requisição, extraem campos-chave e retornam uma resposta no formato JSON necessário.
Node.js
module.exports.handler = function(event, context, callback) {
var event = JSON.parse(event);
var content = {
path: event.path,
method: event.method,
headers: event.headers,
queryParameters: event.queryParameters,
pathParameters: event.pathParameters,
body: event.body
// You can write your own logic here.
}
var response = {
isBase64Encoded: false,
statusCode: '200',
headers: {
'x-custom-header': 'header value'
},
body: content
};
callback(null, response)
};
Python
# -*- coding: utf-8 -*-
import json
def handler(event, context):
event = json.loads(event)
content = {
'path': event['path'],
'method': event['httpMethod'],
'headers': event['headers'],
'queryParameters': event['queryParameters'],
'pathParameters': event['pathParameters'],
'body': event['body']
}
# You can write your own logic here.
rep = {
"isBase64Encoded": "false",
"statusCode": "200",
"headers": {
"x-custom-header": "no"
},
"body": content
}
return json.dumps(rep)
PHP
<?php
function handler($event, $context) {
$event = json_decode($event, $assoc = true);
$content = [
'path' => $event['path'],
'method' => $event['httpMethod'],
'headers' => $event['headers'],
'queryParameters' => $event['queryParameters'],
'pathParameters' => $event['pathParameters'],
'body' => $event['body'],
];
$rep = [
"isBase64Encoded" => "false",
"statusCode" => "200",
"headers" => [
"x-custom-header" => "no",
],
"body" => $content,
];
return json_encode($rep);
}
Java
O Function Compute fornece duas interfaces de handler para Java. Para mais informações sobre o runtime Java, consulte Compilar e implantar um pacote de código.
Opção 1 (recomendada): PojoRequestHandler
PojoRequestHandler<I, O> permite trabalhar com objetos de requisição e resposta tipados em vez de fluxos brutos.
import com.aliyun.fc.runtime.Context;
import com.aliyun.fc.runtime.PojoRequestHandler;
import java.util.HashMap;
import java.util.Map;
public class ApiTriggerDemo implements PojoRequestHandler<ApiRequest, ApiResponse> {
public ApiResponse handleRequest(ApiRequest request, Context context) {
// Obtain API request information.
context.getLogger().info(request.toString());
String path = request.getPath();
String httpMethod = request.getHttpMethod();
String body = request.getBody();
context.getLogger().info("path: " + path);
context.getLogger().info("httpMethod: " + httpMethod);
context.getLogger().info("body: " + body);
// You can write your own logic here.
// Sample API response.
Map headers = new HashMap();
boolean isBase64Encoded = false;
int statusCode = 200;
String returnBody = "";
return new ApiResponse(headers, isBase64Encoded, statusCode, returnBody);
}
}
Defina as classes Plain Old Java Object (POJO) ApiRequest e ApiResponse conforme abaixo. Os métodos set() e get() devem estar completos.
import java.util.Map;
public class ApiRequest {
private String path;
private String httpMethod;
private Map headers;
private Map queryParameters;
private Map pathParameters;
private String body;
private boolean isBase64Encoded;
@Override
public String toString() {
return "Request{" +
"path='" + path + '\'' +
", httpMethod='" + httpMethod + '\'' +
", headers=" + headers +
", queryParameters=" + queryParameters +
", pathParameters=" + pathParameters +
", body='" + body + '\'' +
", isBase64Encoded=" + isBase64Encoded +
'}';
}
public String getPath() { return path; }
public void setPath(String path) { this.path = path; }
public String getHttpMethod() { return httpMethod; }
public void setHttpMethod(String httpMethod) { this.httpMethod = httpMethod; }
public Map getHeaders() { return headers; }
public void setHeaders(Map headers) { this.headers = headers; }
public Map getQueryParameters() { return queryParameters; }
public void setQueryParameters(Map queryParameters) { this.queryParameters = queryParameters; }
public Map getPathParameters() { return pathParameters; }
public void setPathParameters(Map pathParameters) { this.pathParameters = pathParameters; }
public String getBody() { return body; }
public void setBody(String body) { this.body = body; }
public boolean getIsBase64Encoded() { return this.isBase64Encoded; }
public void setIsBase64Encoded(boolean base64Encoded) { this.isBase64Encoded = base64Encoded; }
}
import java.util.Map;
public class ApiResponse {
private Map headers;
private boolean isBase64Encoded;
private int statusCode;
private String body;
public ApiResponse(Map headers, boolean isBase64Encoded, int statusCode, String body) {
this.headers = headers;
this.isBase64Encoded = isBase64Encoded;
this.statusCode = statusCode;
this.body = body;
}
public Map getHeaders() { return headers; }
public void setHeaders(Map headers) { this.headers = headers; }
public boolean getIsBase64Encoded() { return isBase64Encoded; }
public void setIsBase64Encoded(boolean base64Encoded) { this.isBase64Encoded = base64Encoded; }
public int getStatusCode() { return statusCode; }
public void setStatusCode(int statusCode) { this.statusCode = statusCode; }
public String getBody() { return body; }
public void setBody(String body) { this.body = body; }
}
Adicione a seguinte dependência Maven no seu pom.xml:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>apiTrigger</groupId>
<artifactId>apiTrigger</artifactId>
<version>1.0-SNAPSHOT</version>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.8</source>
<target>1.8</target>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>com.aliyun.fc.runtime</groupId>
<artifactId>fc-java-core</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</project>
Opção 2: StreamRequestHandler
StreamRequestHandler oferece acesso direto aos fluxos de entrada e saída brutos. Converta o InputStream para a classe POJO correspondente manualmente. A configuração do pom.xml é a mesma usada para PojoRequestHandler.
import com.aliyun.fc.runtime.Context;
import com.aliyun.fc.runtime.StreamRequestHandler;
import com.google.gson.Gson;
import java.io.*;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
public class ApiTriggerDemo2 implements StreamRequestHandler {
public void handleRequest(InputStream inputStream, OutputStream outputStream, Context context) {
try {
// Convert the InputStream to a string.
BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(inputStream));
StringBuffer stringBuffer = new StringBuffer();
String string = "";
while ((string = bufferedReader.readLine()) != null) {
stringBuffer.append(string);
}
String input = stringBuffer.toString();
context.getLogger().info("inputStream: " + input);
Request req = new Gson().fromJson(input, Request.class);
context.getLogger().info("input req: ");
context.getLogger().info(req.toString());
String bodyReq = req.getBody();
Base64.Decoder decoder = Base64.getDecoder();
context.getLogger().info("body: " + new String(decoder.decode(bodyReq)));
// You can process your own logic here.
// Return structure.
Map headers = new HashMap();
headers.put("x-custom-header", " ");
boolean isBase64Encoded = false;
int statusCode = 200;
Map body = new HashMap();
Response resp = new Response(headers, isBase64Encoded, statusCode, body);
String respJson = new Gson().toJson(resp);
context.getLogger().info("outputStream: " + respJson);
outputStream.write(respJson.getBytes());
} catch (IOException e) {
e.printStackTrace();
} finally {
try {
outputStream.close();
inputStream.close();
} catch (IOException e) {
e.printStackTrace();
}
}
}
class Request {
private String path;
private String httpMethod;
private Map headers;
private Map queryParameters;
private Map pathParameters;
private String body;
private boolean isBase64Encoded;
@Override
public String toString() {
return "Request{" +
"path='" + path + '\'' +
", httpMethod='" + httpMethod + '\'' +
", headers=" + headers +
", queryParameters=" + queryParameters +
", pathParameters=" + pathParameters +
", body='" + body + '\'' +
", isBase64Encoded=" + isBase64Encoded +
'}';
}
public String getBody() {
return body;
}
}
// Function Compute must return the response to API Gateway in the following JSON format.
class Response {
private Map headers;
private boolean isBase64Encoded;
private int statusCode;
private Map body;
public Response(Map headers, boolean isBase64Encoded, int statusCode, Map body) {
this.headers = headers;
this.isBase64Encoded = isBase64Encoded;
this.statusCode = statusCode;
this.body = body;
}
}
}
Etapa 5: Testar a função
O API Gateway passa os dados da requisição para sua função como um evento JSON estruturado. Use um evento de teste para verificar se sua função processa a entrada corretamente antes de conectar o tráfego real.
Na aba Code da página de detalhes da função, clique no ícone
ao lado de Test function e selecione Configure test parameters na lista suspensa.-
No painel Configure test parameters, selecione Create new test event ou Modify existing test event. Insira o nome e o conteúdo do evento e clique em OK. Use o seguinte formato de evento:
{ "path": "api request path", "httpMethod": "request method name", "headers": {all headers, including system headers}, "queryParameters": {query parameters}, "pathParameters": {path parameters}, "body": "string of request payload", "isBase64Encoded": "true|false, indicate if the body is Base64-encoded" } Clique em Test function e verifique o resultado acima da aba Code.
Referência de formato de evento e resposta
Quando o API Gateway chama sua função de evento, ele converte os dados da requisição HTTP em um evento JSON e os transmite à função. Após o processamento, o Function Compute retorna uma resposta JSON. O API Gateway mapeia os campos da resposta de volta para uma resposta HTTP e a envia ao cliente.

Campos do evento de requisição
|
Campo |
Tipo |
Descrição |
|
|
String |
O caminho da requisição da API |
|
|
String |
O método HTTP: GET, POST, PUT, DELETE, etc. |
|
|
Object |
Todos os cabeçalhos da requisição, incluindo cabeçalhos de sistema e personalizados |
|
|
Object |
Pares chave-valor da string de consulta (após |
|
|
Object |
Parâmetros de caminho que identificam um recurso específico dentro da URL |
|
|
String |
O corpo da requisição |
|
|
Boolean |
Indica se o corpo da requisição está codificado em Base64 |
Comportamento de isBase64Encoded:
true: O corpo está codificado em Base64. Decodifique-o antes de processar.false: O corpo não está codificado. Leia-o diretamente.
Formato de resposta
Retorne o resultado da execução no seguinte formato JSON. O API Gateway mapeia esses campos para a resposta HTTP enviada ao cliente.
{
"isBase64Encoded": true|false,
"statusCode": httpStatusCode,
"headers": {response headers},
"body": "..."
}
Se a resposta não seguir este formato, o API Gateway considera o back-end indisponível e retorna um erro 502.
Conectar uma função web ao API Gateway
Com uma função web, o API Gateway encaminha o tráfego HTTP bruto para o endpoint de rede interna da sua função. Sua função atua como um servidor HTTP e processa as requisições diretamente — sem necessidade de conversão de evento JSON.
Pré-requisitos
Antes de começar, verifique se você tem:
Uma conta Alibaba Cloud com acesso ao Function Compute e ao API Gateway
Uma região selecionada para ambos os serviços (coloque-os na mesma região para evitar taxas de tráfego de rede pública)
Etapa 1: Criar uma função web
Crie uma função web no console do Function Compute 3.0. Para mais informações, consulte Criar uma função web.
Um gatilho HTTP é criado para a função web por padrão. Copie o endpoint de rede interna para uso na Etapa 2.

Etapa 2: Criar um serviço de back-end
-
Faça login no console do API Gateway, selecione uma região e, no painel de navegação à esquerda, escolha Manage APIs > Backend Services. No canto superior direito, clique em Create Backend Service. Configure as informações necessárias e clique em Confirm.

-
Na página Backend Services, clique no serviço de back-end recém-criado. Clique na aba Production. Na seção Basic Information, clique em Create, insira o endpoint de rede interna do gatilho HTTP da função web e clique em Publish.

Etapa 3: Criar e publicar uma API
Use grupos de APIs para organizar APIs relacionadas e aplicar políticas unificadas de segurança e gerenciamento de tráfego.
Faça login no console do API Gateway. No painel de navegação à esquerda, escolha Manage APIs > API groups e clique em Create group.
-
Na caixa de diálogo Create group, selecione uma instância, insira
FC-Grouppara Group name, defina BasePath como/e clique em Confirm.Coloque o grupo de APIs na mesma região da sua função. Se estiverem em regiões diferentes, o API Gateway acessará o Function Compute pela rede pública, gerando taxas de tráfego.

-
Na página de lista de grupos, localize o grupo desejado e clique em Manage APIs na coluna Actions. Clique em Create API, configure as definições necessárias e clique em Next.

Na aba Define API request, defina Request path como
/e clique em Next.-
Na aba Define backend service, configure as definições conforme mostrado na figura e clique em Next.

Na aba Define response, mantenha as configurações padrão e clique em Create. Quando solicitado, clique em Publish.
-
Na caixa de diálogo Publish API, configure as opções de publicação e clique em Publish.

Etapa 4: Criar um aplicativo e conceder autorização
A API publicada na Etapa 3 usa autenticação Alibaba Cloud APP. Crie um aplicativo e conceda a ele acesso à API.
Faça login no console do API Gateway. No painel de navegação à esquerda, escolha Call APIs > Apps.
Na página Apps, clique em Create app no canto superior direito. Insira
fcApppara App name e clique em Confirm.-
Clique no aplicativo
fcApppara abrir sua página de detalhes. O aplicativo possui dois métodos de autenticação:
AppKey: Usa um par AppKey e AppSecret (semelhante a usuário e senha). Passe o AppKey como parâmetro de requisição; o AppSecret é usado para calcular a assinatura da requisição.
AppCode: Um método de autenticação mais simples para uso direto em chamadas de API.
No painel de navegação à esquerda, escolha Manage APIs > APIs. Localize a API criada. Na coluna Actions, clique em
> Authorize.-
Na página de autorização, defina Stage como Production. Pesquise por
fcApp, clique em Add e clique em Confirm.
Etapa 5: Verificar o resultado
Chame a API publicada usando autenticação AppCode. O exemplo a seguir utiliza curl:
No console do API Gateway, escolha Call APIs > Apps. Abra a página de detalhes do aplicativo
fcApppara obter o AppCode.-
Chame a API:
curl -i -X GET "http://fd6f8e2b7bf44ab181a56****-cn-hangzhou.alicloudapi.com" \ -H "Authorization:APPCODE 7d2b7e4945ce44028ab00***"
Perguntas frequentes
Uma função acionada pelo API Gateway retorna um erro 502, mas os logs da função mostram que ela foi concluída com sucesso. Por quê?
A resposta do Function Compute não correspondeu ao formato exigido. O API Gateway espera os campos isBase64Encoded, statusCode, headers e body na resposta JSON. Se algum campo estiver ausente ou malformado, o API Gateway trata o back-end como indisponível. Verifique a referência de formato de evento e resposta e confirme se o valor de retorno da sua função corresponde à estrutura esperada.
Como defino o Content-Type da resposta?
Defina o Content-Type ao configurar a API no API Gateway. Para detalhes, consulte Conectar ao Function Compute 3.0 (função web) através do API Gateway.
Uma função opera corretamente, mas retorna um erro 503 após um período de inatividade. Por quê?
O ambiente de execução da função foi reciclado durante o período ocioso. Quando a próxima requisição chega, o Function Compute precisa de tempo para inicializar um novo ambiente — isso é uma inicialização a frio. Se a inicialização exceder o tempo limite configurado no API Gateway, o API Gateway trata o back-end como indisponível e retorna 503. Para resolver isso, estenda o período de tempo limite na configuração do API Gateway.
Por que a função recebe um corpo codificado em Base64 do API Gateway?
O API Gateway ignora a codificação Base64 apenas para transmissões baseadas em FORM (quando você seleciona mapeamento de parâmetros de entrada no API Gateway). Todos os outros formatos de corpo são codificados em Base64 para evitar perda de dados durante a transmissão. Verifique o campo isBase64Encoded no evento: se for true, decodifique o corpo antes de processar. Para mais detalhes sobre o formato do evento, consulte Formato de evento de gatilho.