Invoke a function with HTTP requests - Function Compute - Centro de documentación de Alibaba Cloud

Un disparador HTTP expone una función como un endpoint HTTP(S), conocido como URL de función. Cuando un cliente llama a la URL de función, Function Compute convierte la solicitud HTTP en un objeto de evento y lo pasa al controlador de su función. Una vez que la función devuelve el resultado, Function Compute asigna la salida a una respuesta HTTP y la envía al cliente.

Este tema describe el comportamiento del disparador HTTP en los entornos de ejecución integrados. Para los entornos de ejecución personalizados, consulte Web functions.

En Function Compute 3.0, el comportamiento del disparador HTTP en los entornos de ejecución integrados difiere notablemente del de Function Compute 2.0. Para más detalles, consulte How it works . En los entornos de ejecución personalizados y de contenedor personalizado, el comportamiento se mantiene igual que en Function Compute 2.0.

Funcionamiento

Cuando un cliente llama a la URL de su función:

Function Compute asigna la solicitud HTTP a un objeto de evento (event).
El objeto de evento se pasa al controlador de su función.
Una vez que la función devuelve el resultado, Function Compute asigna la salida a una respuesta HTTP y la envía de vuelta al cliente.

Estructura de la solicitud

Formato

Function Compute asigna la solicitud HTTP entrante a un objeto de evento con la siguiente estructura:

{
    "version": "v1",
    "rawPath": "/example",
    "body": "Hello FC!",
    "isBase64Encoded": false,
    "headers": {
        "header1": "value1",
        "header2": "value1,value2"
    },
    "queryParameters": {
        "parameter1": "value1",
        "parameter2": "value1,value2"
    },
    "requestContext": {
        "accountId": "123456*********",
        "domainName": "<http-trigger-id>.<region-id>.fcapp.run",
        "domainPrefix": "<http-trigger-id>",
        "http": {
            "method": "GET",
            "path": "/example",
            "protocol": "HTTP/1.1",
            "sourceIp": "11.11.11.**",
            "userAgent": "PostmanRuntime/7.32.3"
        },
        "requestId": "1-64f6cd87-*************",
        "time": "2023-09-05T06:41:11Z",
        "timeEpoch": "1693896071895"
    }
}

Parámetros

Parámetro	Descripción	Ejemplo
`version`	Versión del formato de carga útil. El único valor compatible es `v1`.	`v1`
`rawPath`	Ruta de la solicitud codificada en URL. Para una URL de solicitud como `https://{url-id}.{region}.fcapp.run/example`, este valor es `/example`. Para la ruta decodificada, consulte `requestContext.http.path`.	`/example`
`body`	Cuerpo de la solicitud. Los datos binarios se codifican en Base64.	`Hello FC!`
`isBase64Encoded`	Indica si el cuerpo de la solicitud está codificado en Base64. Valores válidos: `true`, `false`.	`false`
`headers`	Encabezados de la solicitud como pares clave-valor. Si una clave tiene varios valores, estos se separan por comas. En Function Compute 3.0, la primera letra de cada clave de encabezado se escribe en mayúscula (normalización). Consulte Why does the first letter of the header key become uppercase when I use an HTTP trigger to invoke a function?	`{"Header1": "value1", "Header2": "value1,value2"}`
`queryParameters`	Parámetros de consulta como un objeto JSON. Para una URL como `https://{url-id}.{region}.fcapp.run/example?key1=value1`, este valor es `{"key1": "value1"}`. Los valores múltiples para la misma clave se separan por comas.	`{"parameter1": "value1", "parameter2": "value1,value2"}`
`requestContext`	Metadatos adicionales de la solicitud, incluidos el ID de solicitud, la marca de tiempo y la información del emisor.	—
`requestContext.accountId`	ID de la cuenta de Alibaba Cloud propietaria de la función.	`123456*********`
`requestContext.domainName`	Nombre de dominio del disparador HTTP.	`<http-trigger-id>.<region-id>.fcapp.run`
`requestContext.domainPrefix`	Prefijo de dominio del disparador HTTP.	`<http-trigger-id>`
`requestContext.http`	Información detallada sobre la solicitud HTTP.	—
`requestContext.http.method`	Método HTTP. Valores válidos: `GET`, `POST`, `PUT`, `HEAD`, `OPTIONS`, `PATCH`, `DELETE`.	`GET`
`requestContext.http.path`	Ruta de la solicitud decodificada. Para una URL de solicitud como `https://{url-id}.{region}.fcapp.run/example?name=Jane`, este valor es `/example`.	`/example`
`requestContext.http.protocol`	Protocolo de la solicitud.	`HTTP/1.1`
`requestContext.http.sourceIp`	IP del par de la conexión TCP directa (RemoteAddr). Consulte la nota a continuación.	`11.11.XX.XX`
`requestContext.http.userAgent`	Valor del encabezado de solicitud `user-agent`.	`PostmanRuntime/7.32.3`
`requestContext.requestId`	ID de solicitud para rastrear los registros de invocación.	`1-64f6cd87-*************`
`requestContext.time`	Marca de tiempo de la solicitud en formato ISO 8601.	`2023-09-05T06:41:11Z`
`requestContext.timeEpoch`	Marca de tiempo de la solicitud en tiempo UNIX (milisegundos).	`1693896071895`

Aviso

sourceIp es la IP del par de la conexión TCP directa, no necesariamente la IP original del cliente. Si la solicitud no se reenvía mediante un proxy, sourceIp corresponde a la IP del cliente. Si la solicitud pasa por uno o más proxies, sourceIp es la IP del último proxy. Para obtener la IP original del cliente cuando las solicitudes pasan por proxies, lea el encabezado X-Forwarded-For. Para más detalles, consulte How do I obtain the original IP address of a client when an HTTP trigger invokes a function that uses a built-in runtime?

Lógica de asignación

Function Compute asigna la solicitud HTTP al objeto de evento de la siguiente manera:

Encabezados de la solicitud HTTP → event.headers
Parámetros de consulta HTTP → event.queryParameters
Contexto de la solicitud (ID de solicitud, marca de tiempo, identidad del emisor) → event.requestContext
Cuerpo de la solicitud POST → event.body

Codificación Base64

Function Compute revisa el encabezado Content-Type para decidir si codifica el cuerpo de la solicitud en Base64.

`Content-Type`	`isBase64Encoded`	Manejo del cuerpo
`text/*`	`false`	Se pasa tal cual
`application/json`	`false`	Se pasa tal cual
`application/ld+json`	`false`	Se pasa tal cual
`application/xhtml+xml`	`false`	Se pasa tal cual
`application/xml`	`false`	Se pasa tal cual
`application/atom+xml`	`false`	Se pasa tal cual
`application/javascript`	`false`	Se pasa tal cual
Cualquier otro valor	`true`	Se codifica en Base64 antes de pasarlo a la función

Ejemplos de asignación de solicitudes

GET

Solicitud HTTP

Objeto de evento

GET /?parameter1=value1&parameter2=value2 HTTP/1.1

{"version":"v1","rawPath":"/","headers":{"Accept":"*/*","User-Agent":"CurlHttpClient"},"queryParameters":{"parameter1":"value1","parameter2":"value2"},"body":"","isBase64Encoded":true,"requestContext":{"accountId":"1327**********","domainName":"example.cn-hangzhou.fcapp.run","domainPrefix":"example","requestId":"1-67aee50c-****-**********","time":"2025-02-14T06:39:08Z","timeEpoch":"1739515148145","http":{"method":"GET","path":"/","protocol":"HTTP/1.1","sourceIp":"40.XX.XX.XX","userAgent":"CurlHttpClient"}}}

Para enviar esta solicitud desde la CLI (reemplace https://example.cn-hangzhou.fcapp.run con la URL de su función):

curl -v "https://example.cn-hangzhou.fcapp.run?parameter1=value1&parameter2=value2"

POST

Solicitud HTTP Objeto de evento

Solicitud HTTP	Objeto de evento
`POST / HTTP/1.1 Content-Type: application/json`	{"version":"v1","rawPath":"/","headers":{"Accept":"/","Content-Length":"20","Content-Type":"application/json","User-Agent":"curl/8.7.1"},"queryParameters":{},"body":"{\"message\": \"Hello\"}","isBase64Encoded":false,"requestContext":{"accountId":"1327********","domainName":"example.cn-hangzhou.fcapp.run","domainPrefix":"example","requestId":"1-67aee50c--********","time":"2025-02-14T06:39:08Z","timeEpoch":"1739515148145","http":{"method":"POST","path":"/","protocol":"HTTP/1.1","sourceIp":"40.XX.XX.XX","userAgent":"CurlHttpClient"}}}

POST / HTTP/1.1
Content-Type: application/json

{"version":"v1","rawPath":"/","headers":{"Accept":"*/*","Content-Length":"20","Content-Type":"application/json","User-Agent":"curl/8.7.1"},"queryParameters":{},"body":"{\"message\": \"Hello\"}","isBase64Encoded":false,"requestContext":{"accountId":"1327**********","domainName":"example.cn-hangzhou.fcapp.run","domainPrefix":"example","requestId":"1-67aee50c-****-**********","time":"2025-02-14T06:39:08Z","timeEpoch":"1739515148145","http":{"method":"POST","path":"/","protocol":"HTTP/1.1","sourceIp":"40.XX.XX.XX","userAgent":"CurlHttpClient"}}}

Para enviar esta solicitud desde la CLI (reemplace https://example.cn-hangzhou.fcapp.run con la URL de su función):

curl -v -H "Content-Type: application/json" -d '{"message": "Hello"}' "https://example.cn-hangzhou.fcapp.run"

Para forzar la codificación en Base64 del cuerpo de la solicitud, establezca Content-Type como application/x-www-form-urlencoded .

Estructura de la respuesta

Formato

La salida de su función se analiza sintácticamente en una estructura de respuesta antes de asignarse a la respuesta HTTP:

{
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json",
        "Custom-Header-1": "Custom Value"
    },
    "isBase64Encoded": false,
    "body": "{\"message\":\"Hello FC!\"}"
}

Lógica de asignación

Function Compute asigna la salida de su función a la respuesta HTTP según si la salida es un JSON válido que contiene un campo statusCode.

**Cuando la salida es un JSON válido con statusCode:**

Campo de la estructura de respuesta	Respuesta HTTP
`statusCode`	Código de estado
`headers["Content-Type"]`	Encabezado `Content-Type` (el valor predeterminado es `application/json` si está ausente)
`body`	Cuerpo de la respuesta
`isBase64Encoded`	Indica si se debe decodificar el cuerpo en Base64 antes de enviarlo (el valor predeterminado es `false` si está ausente)

**Cuando la salida es un JSON válido sin statusCode, o no es JSON:**

Function Compute utiliza los siguientes valores predeterminados:

Campo	Valor predeterminado
`statusCode`	`200`
`Content-Type`	`application/json`
`body`	Salida de la función tal cual
`isBase64Encoded`	`false`

Ejemplos de asignación de respuestas

A continuación se muestran ejemplos de cómo la salida de la función pasa por el análisis sintáctico hasta convertirse en la respuesta HTTP final.

Salida para una respuesta de cadena

Salida de la función	Estructura de respuesta analizada	Respuesta HTTP (que recibe el cliente)
`Hello World!`	`{"statusCode":200,"body":"Hello World!","headers":{"content-type":"application/json"},"isBase64Encoded":false}`	`HTTP/1.1 200 OK Content-Disposition: attachment Content-Length: 12 Content-Type: application/json X-Fc-Request-Id: 1-64f6d6e7-e01edb1cce58240ed59b59d9 Hello World!`

Salida para una respuesta JSON

Salida de la función	Estructura de respuesta analizada	Respuesta HTTP (que recibe el cliente)
`{"message": "Hello World!"}`	`{"statusCode":200,"body":"{\"message\": \"Hello World!\"}","headers":{"content-type":"application/json"},"isBase64Encoded":false}`	`HTTP/1.1 200 OK Content-Disposition: attachment Content-Length: 27 Content-Type: application/json X-Fc-Request-Id: 1-64f6d867-7302fc1ac6338b6fd2adb782 {"message": "Hello World!"}`

Salida para una respuesta personalizada

Salida de la función	Estructura de respuesta analizada	Respuesta HTTP (que recibe el cliente)
`{"statusCode":201,"headers":{"Content-Type":"application/json","My-Custom-Header":"Custom Value"},"body":{"message":"Hello, world!"},"isBase64Encoded":false}`	`{"statusCode":201,"headers":{"Content-Type":"application/json","My-Custom-Header":"Custom Value"},"body":{"message":"Hello, world!"},"isBase64Encoded":false}`	`HTTP/1.1 201 OK Content-Type: application/json My-Custom-Header: Custom Value X-Fc-Request-Id: 1-64f6dcb3-e787580749d3ba13b047ce14 {"message": "Hello world!"}`

Decodificación Base64

Si su función devuelve un JSON válido con isBase64Encoded establecido en true, Function Compute decodifica el body en Base64 antes de asignarlo al cuerpo de la respuesta HTTP. Si la decodificación falla, Function Compute devuelve directamente el valor de body sin reportar un error.

Encabezados de respuesta

Function Compute agrega automáticamente el encabezado X-Fc-Request-Id a cada respuesta. Este encabezado identifica de forma única la solicitud y resulta útil para rastrear registros y diagnosticar errores. Además de X-Fc-Request-Id, Function Compute no agrega ningún otro encabezado de respuesta de forma predeterminada.

Aviso

Los encabezados personalizados con el prefijo X-Fc- no son compatibles. Los siguientes encabezados están reservados por Function Compute y se ignoran si su función los devuelve:

connection
content-length
date
keep-alive
server
content-disposition

Manejo de errores

Las invocaciones mediante disparador HTTP y las invocaciones directas de API manejan los errores de función de manera distinta.

Tipo de invocación	Comportamiento ante errores	Código de estado HTTP
Invocación directa de API	El mensaje de error se devuelve en el cuerpo de la respuesta	`200`
Disparador HTTP (URL de función)	El mensaje de error se oculta; se devuelve `Internal Server Error`	`502`

Por ejemplo, una invocación directa de API que encuentra un error ModuleNotFoundError de Python devuelve los siguientes detalles de error:

{
    "errorMessage": "Unable to import module 'index'",
    "errorType": "ImportModuleError",
    "stackTrace": [
        "ModuleNotFoundError: No module named 'not_exist_module'"
    ]
}

Cuando una función invocada mediante un disparador HTTP encuentra un error, el cliente recibe una respuesta similar a la siguiente:

HTTP/1.1 502 Bad Gateway
Content-Disposition: attachment
Content-Type: application/json
X-Fc-Request-Id: 1-64f6df91-fe144d52e4fd27afe3d8dd6f
Content-Length: 21

Internal Server Error

Utilice el valor de X-Fc-Request-Id para buscar los detalles completos del error en los registros de invocación de su función.

Temas relacionados

Si está escribiendo código de función para un entorno de ejecución integrado, consulte la documentación del controlador correspondiente a su lenguaje: