Todos los productos
Search
Centro de documentos

Function Compute:Desencadenadores de API Gateway

Última actualización: Sep 06, 2026

Function Compute admite API Gateway como origen de eventos. Configure Function Compute como el servicio de backend de una API; API Gateway reenvía las solicitudes entrantes a la función asociada y devuelve el resultado de la ejecución al cliente.

Cuándo usar desencadenadores de API Gateway

Los desencadenadores de API Gateway y los desencadenadores HTTP exponen funciones como endpoints HTTP. Elija según sus requisitos:

Capacidad

Desencadenador de API Gateway

Desencadenador HTTP

Listas de permitidos y bloqueados de IP

Compatible

No compatible

Autenticación (AppKey, AppCode)

Compatible

No compatible

Conformado de tráfico

Compatible

No compatible

Transformación de datos

Compatible

No compatible

Use un desencadenador de API Gateway cuando necesite control de acceso avanzado, autenticación o gestión de tráfico. Para una exposición HTTP simple, un desencadenador HTTP es suficiente.

API Gateway admite funciones de evento y funciones web como su backend. El modelo de integración difiere:

  • Función de evento: API Gateway convierte la solicitud HTTP en un evento JSON estructurado y lo pasa a su función. Su función debe devolver una respuesta JSON en un formato específico.

  • Función web: API Gateway reenvía la solicitud HTTP sin procesar al endpoint de red interna de su función. Su función gestiona la solicitud directamente como un servidor HTTP.

Conectar una función de evento a API Gateway

Requisitos previos

Antes de empezar, asegúrese de contar con:

  • Una cuenta de Alibaba Cloud con acceso a Function Compute y API Gateway

  • Una región seleccionada para ambos servicios (ubíquelos en la misma región para evitar cargos de tráfico de red pública)

Paso 1: Cree una función de evento

Cree una función de evento en la consola de Function Compute 3.0. Para obtener más información, consulte Create an event function.

Paso 2: Cree un servicio de backend de API Gateway

Defina un servicio de backend en API Gateway y vincúlelo a su función.

  1. Inicie sesión en la consola de API Gateway, seleccione una región y, en el panel de navegación izquierdo, elija Manage APIs > Backend Services. En la esquina superior derecha, haga clic en Create Backend Service. Configure la información obligatoria y haga clic en Confirm.

    image

  2. En la página Backend Services, haga clic en el servicio de backend que acaba de crear. Haga clic en la pestaña Production. En la sección Basic Information, haga clic en Create, seleccione la función de evento del Paso 1 y luego haga clic en Publish.

    image

Paso 3: Cree y publique una API

  1. En la consola de API Gateway, cree un grupo de API. Ubique el grupo en la misma región que su función.

    Si el grupo de API y la función están en regiones diferentes, API Gateway accede a Function Compute a través de la red pública, lo que genera cargos de tráfico. Para menor latencia y mejor seguridad de los datos, use la misma región.
  2. Cree y publique una API con las configuraciones clave que se muestran a continuación. Mantenga los valores predeterminados para todos los demás campos.

    Elemento de configuración

    Valor

    Security authentication

    Sin autenticación

    Configuration mode

    Usar un servicio de backend existente

    Backend service type

    Function Compute

    Version

    Function Compute 3.0

    Function type

    Función de evento

    Backend services

    Seleccione el servicio de backend que creó en el Paso 2

    image

Paso 4: Escriba el código de la función

  1. Inicie sesión en la consola de Function Compute. En el panel de navegación izquierdo, haga clic en Functions.

  2. En la barra de navegación superior, seleccione la región. En la página Functions, haga clic en la función que desea gestionar.

  3. En la página de detalles de la función, haga clic en la pestaña Code. Escriba su código en el editor y haga clic en Deploy.

Todos los ejemplos leen el evento de solicitud, extraen los campos clave y devuelven una respuesta en el formato JSON obligatorio.

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

Function Compute proporciona dos interfaces de controlador para Java. Para obtener más información sobre el runtime de Java, consulte Compile and deploy a code package.

Opción 1 (recomendada): PojoRequestHandler

PojoRequestHandler<I, O> le permite trabajar con objetos de solicitud y respuesta con tipo en lugar de flujos sin procesar.

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 las clases ApiRequest y ApiResponse como objetos Java simples (POJO), como se muestra a continuación. Los métodos set() y get() deben 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; }
}

Agregue la dependencia de Maven que se muestra a continuación en su 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>

Opción 2: StreamRequestHandler

StreamRequestHandler le proporciona acceso directo a los flujos de entrada y salida sin procesar. Convierta el InputStream manualmente a la clase POJO correspondiente. La configuración de pom.xml es la misma que 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;
        }
    }
}

Paso 5: Pruebe la función

API Gateway pasa los datos de solicitud a su función como un evento JSON estructurado. Use un evento de prueba para comprobar que su función gestiona correctamente la entrada antes de conectar tráfico real.

  1. En la pestaña Code de la página de detalles de la función, haga clic en el icono image.png junto a Test function y seleccione Configure test parameters en la lista desplegable.

  2. En el panel Configure test parameters, seleccione Create new test event o Modify existing test event. Introduzca el nombre y el contenido del evento y, a continuación, haga clic en OK. Use el formato de evento que se muestra a continuación:

    {
        "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"
    }
  3. Haga clic en Test function y compruebe el resultado encima de la pestaña Code.

Referencia de formato de evento y respuesta

Cuando API Gateway llama a su función de evento, convierte los datos de la solicitud HTTP en un evento JSON y los pasa a la función. Después de procesar el evento, Function Compute devuelve una respuesta JSON. API Gateway asigna los campos de la respuesta a una respuesta HTTP y la envía al cliente.

principle

Campos del evento de solicitud

Campo

Tipo

Descripción

path

String

La ruta de la solicitud de API

httpMethod

String

El método HTTP: GET, POST, PUT, DELETE, etc.

headers

Object

Todos los encabezados de solicitud, incluidos los encabezados del sistema y personalizados

queryParameters

Object

Pares clave-valor de la cadena de consulta (después de ? en la URL)

pathParameters

Object

Parámetros de ruta que identifican un recurso específico dentro de la URL

body

String

El cuerpo de la solicitud

isBase64Encoded

Boolean

Indica si el cuerpo de la solicitud está codificado en Base64

Comportamiento de isBase64Encoded:

  • true: El cuerpo está codificado en Base64. Decodifíquelo antes de procesarlo.

  • false: El cuerpo no está codificado. Léaló directamente.

Formato de respuesta

Devuelva el resultado de la ejecución en el formato JSON que se muestra a continuación. API Gateway asigna estos campos a la respuesta HTTP enviada al cliente.

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": {response headers},
    "body": "..."
}

Si la respuesta no sigue este formato, API Gateway trata el backend como no disponible y devuelve un error 502.

Conectar una función web a API Gateway

Con una función web, API Gateway reenvía el tráfico HTTP sin procesar al endpoint de red interna de su función. Su función actúa como un servidor HTTP y gestiona las solicitudes directamente; no se requiere conversión de evento JSON.

Requisitos previos

Antes de empezar, asegúrese de contar con:

  • Una cuenta de Alibaba Cloud con acceso a Function Compute y API Gateway

  • Una región seleccionada para ambos servicios (ubíquelos en la misma región para evitar cargos de tráfico de red pública)

Paso 1: Cree una función web

Cree una función web en la consola de Function Compute 3.0. Para obtener más información, consulte Create a web function.

De forma predeterminada, se crea un desencadenador HTTP para la función web. Copie el endpoint de red interna para usarlo en el Paso 2.

image

Paso 2: Cree un servicio de backend

  1. Inicie sesión en la consola de API Gateway, seleccione una región y, en el panel de navegación izquierdo, elija Manage APIs > Backend Services. En la esquina superior derecha, haga clic en Create Backend Service. Configure la información obligatoria y haga clic en Confirm.

    image

  2. En la página Backend Services, haga clic en el servicio de backend que acaba de crear. Haga clic en la pestaña Production. En la sección Basic Information, haga clic en Create, introduzca el endpoint de red interna del desencadenador HTTP de la función web y luego haga clic en Publish.

    image

Paso 3: Cree y publique una API

Use los grupos de API para organizar las API relacionadas y aplicar políticas unificadas de seguridad y gestión de tráfico.

  1. Inicie sesión en la consola de API Gateway. En el panel de navegación izquierdo, elija Manage APIs > API groups y haga clic en Create group.

  2. En el cuadro de diálogo Create group, seleccione una instancia, introduzca FC-Group para Group name, establezca BasePath en / y haga clic en Confirm.

    Ubique el grupo de API en la misma región que su función. Si están en regiones diferentes, API Gateway accede a Function Compute a través de la red pública, lo que genera cargos de tráfico.

    image

  3. En la página de lista de grupos, busque el grupo de destino y haga clic en Manage APIs en la columna Actions. Haga clic en Create API, configure los ajustes obligatorios y haga clic en Next.

    image

  4. En la pestaña Define API request, establezca Request path en / y haga clic en Next.

  5. En la pestaña Define backend service, configure los ajustes como se muestra en la figura y haga clic en Next.

    image

  6. En la pestaña Define response, mantenga los ajustes predeterminados y haga clic en Create. Cuando se le solicite, haga clic en Publish.

  7. En el cuadro de diálogo Publish API, configure los ajustes de publicación y haga clic en Publish.

    image

Paso 4: Cree una aplicación y otorgue autorización

La API publicada en el Paso 3 usa autenticación de Alibaba Cloud APP. Cree una aplicación y otórguele acceso a la API.

  1. Inicie sesión en la consola de API Gateway. En el panel de navegación izquierdo, elija Call APIs > Apps.

  2. En la página Apps, haga clic en Create app en la esquina superior derecha. Introduzca fcApp para App name y haga clic en Confirm.

  3. Haga clic en la aplicación fcApp para abrir su página de detalles. La aplicación tiene dos métodos de autenticación: image

    • AppKey: Usa un par AppKey y AppSecret (similar a una cuenta y una contraseña). El AppKey se pasa como parámetro de solicitud; el AppSecret se usa para calcular la firma de la solicitud.

    • AppCode: Un método de autenticación más simple para usar directamente en llamadas a la API.

  4. En el panel de navegación izquierdo, elija Manage APIs > APIs. Busque la API que creó. En la columna Actions, haga clic en image > Authorize.

  5. En la página de autorización, establezca Stage en Production. Busque fcApp, haga clic en Add y luego haga clic en Confirm.

    image

Paso 5: Compruebe el resultado

Llame a la API publicada mediante autenticación AppCode. A continuación se muestra un ejemplo con curl:

  1. En la consola de API Gateway, elija Call APIs > Apps. Abra la página de detalles de la aplicación fcApp para obtener el AppCode.

  2. Llame a la API:

    curl -i -X GET "http://fd6f8e2b7bf44ab181a56****-cn-hangzhou.alicloudapi.com" \
      -H "Authorization:APPCODE 7d2b7e4945ce44028ab00***"

Preguntas frecuentes

Una función desencadenada por API Gateway devuelve un error 502, pero los registros de la función muestran que se completó correctamente. ¿Por qué?

La respuesta de Function Compute no coincidió con el formato obligatorio. API Gateway espera los campos isBase64Encoded, statusCode, headers y body en la respuesta JSON. Si falta algún campo o tiene un formato incorrecto, API Gateway trata el backend como no disponible. Consulte la referencia de formato de evento y respuesta y compruebe que el valor devuelto por su función coincide con la estructura esperada.

¿Cómo se establece el Content-Type de la respuesta?

Establezca el Content-Type al configurar la API en API Gateway. Para obtener más información, consulte Connect to Function Compute 3.0 (web function) through API Gateway.content-type

Una función funciona correctamente, pero devuelve un error 503 después de un periodo de inactividad. ¿Por qué?

El entorno de ejecución de la función se recicló durante el periodo de inactividad. Cuando llega la siguiente solicitud, Function Compute necesita tiempo para inicializar un nuevo entorno; esto es un arranque en frío. Si la inicialización excede el tiempo de espera configurado en API Gateway, API Gateway trata el backend como no disponible y devuelve 503. Para resolverlo, amplíe el periodo de tiempo de espera en la configuración de API Gateway.

¿Por qué la función recibe un cuerpo codificado en Base64 desde API Gateway?

API Gateway omite la codificación Base64 solo para transmisiones basadas en FORM (cuando selecciona la asignación de parámetros de entrada en API Gateway). Todos los demás formatos de cuerpo se codifican en Base64 para evitar la pérdida de datos durante la transmisión. Compruebe el campo isBase64Encoded en el evento: si es true, decodifique el cuerpo antes de procesarlo. Para obtener más información sobre el formato del evento, consulte Trigger event format.