Invoke a function with HTTP requests - Function Compute: Central de Documentação do Alibaba Cloud

Um gatilho HTTP expõe uma função como um endpoint HTTP(S), chamado URL da função. Quando um cliente chama a URL da função, o Function Compute converte a solicitação HTTP em um objeto de evento e o passa ao handler da função. Após o retorno da função, o Function Compute mapeia a saída para uma resposta HTTP e a envia ao cliente.

Este tópico aborda o comportamento do gatilho HTTP em runtimes integrados. Para runtimes personalizados, consulte Web functions.

No Function Compute 3.0, o comportamento do gatilho HTTP em runtimes integrados difere significativamente do Function Compute 2.0. Para obter detalhes, consulte How it works . Para runtimes personalizados e runtimes de Custom Container, o comportamento permanece igual ao do Function Compute 2.0.

Como funciona

Quando um cliente chama a URL da sua função:

O Function Compute mapeia a solicitação HTTP para um objeto de evento (event).
O objeto de evento é passado ao handler da sua função.
Após o retorno da função, o Function Compute mapeia a saída para uma resposta HTTP e a envia de volta ao cliente.

Estrutura da solicitação

Formato

O Function Compute mapeia a solicitação HTTP recebida para um objeto de evento com a seguinte estrutura:

{
    "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	Descrição	Exemplo
`version`	Versão do formato do payload. O único valor compatível é `v1`.	`v1`
`rawPath`	Caminho da solicitação codificado por URL. Para uma URL de solicitação como `https://{url-id}.{region}.fcapp.run/example`, este valor é `/example`. Para o caminho decodificado, consulte `requestContext.http.path`.	`/example`
`body`	Corpo da solicitação. Dados binários são codificados em Base64.	`Hello FC!`
`isBase64Encoded`	Indica se o corpo da solicitação está codificado em Base64. Valores válidos: `true`, `false`.	`false`
`headers`	Cabeçalhos da solicitação como pares chave-valor. Se uma chave tiver vários valores, eles serão separados por vírgulas. No Function Compute 3.0, a primeira letra de cada chave de cabeçalho é convertida para maiúscula (normalização). 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 um objeto JSON. Para uma URL como `https://{url-id}.{region}.fcapp.run/example?key1=value1`, este valor é `{"key1": "value1"}`. Vários valores para a mesma chave são separados por vírgulas.	`{"parameter1": "value1", "parameter2": "value1,value2"}`
`requestContext`	Metadados adicionais da solicitação, incluindo ID da solicitação, timestamp e informações do chamador.	—
`requestContext.accountId`	ID da conta Alibaba Cloud proprietária da função.	`123456*********`
`requestContext.domainName`	Nome de domínio do gatilho HTTP.	`<http-trigger-id>.<region-id>.fcapp.run`
`requestContext.domainPrefix`	Prefixo de domínio do gatilho HTTP.	`<http-trigger-id>`
`requestContext.http`	Informações detalhadas sobre a solicitação HTTP.	—
`requestContext.http.method`	Método HTTP. Valores válidos: `GET`, `POST`, `PUT`, `HEAD`, `OPTIONS`, `PATCH`, `DELETE`.	`GET`
`requestContext.http.path`	Caminho da solicitação decodificado. Para uma URL de solicitação como `https://{url-id}.{region}.fcapp.run/example?name=Jane`, este valor é `/example`.	`/example`
`requestContext.http.protocol`	Protocolo da solicitação.	`HTTP/1.1`
`requestContext.http.sourceIp`	IP par da conexão TCP direta (RemoteAddr). Consulte a nota abaixo.	`11.11.XX.XX`
`requestContext.http.userAgent`	Valor do cabeçalho de solicitação `user-agent`.	`PostmanRuntime/7.32.3`
`requestContext.requestId`	ID da solicitação para rastreamento de logs de invocação.	`1-64f6cd87-*************`
`requestContext.time`	Timestamp da solicitação no formato ISO 8601.	`2023-09-05T06:41:11Z`
`requestContext.timeEpoch`	Timestamp da solicitação em tempo UNIX (milissegundos).	`1693896071895`

Aviso

sourceIp é o IP par da conexão TCP direta, não necessariamente o IP original do cliente. Se a solicitação não for encaminhada por um proxy, sourceIp corresponde ao IP do cliente. Caso a solicitação passe por um ou mais proxies, sourceIp será o IP do último proxy. Para obter o IP original do cliente quando as solicitações passam por proxies, leia o cabeçalho X-Forwarded-For. Para obter detalhes, 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 mapeamento

O Function Compute mapeia a solicitação HTTP para o objeto de evento da seguinte forma:

Cabeçalhos da solicitação HTTP → event.headers
Parâmetros de consulta HTTP → event.queryParameters
Contexto da solicitação (ID da solicitação, timestamp, identidade do chamador) → event.requestContext
Corpo da solicitação POST → event.body

Codificação Base64

O Function Compute verifica o cabeçalho Content-Type para decidir se deve codificar o corpo da solicitação em Base64.

`Content-Type`	`isBase64Encoded`	Tratamento do corpo
`text/*`	`false`	Transmitido como está
`application/json`	`false`	Transmitido como está
`application/ld+json`	`false`	Transmitido como está
`application/xhtml+xml`	`false`	Transmitido como está
`application/xml`	`false`	Transmitido como está
`application/atom+xml`	`false`	Transmitido como está
`application/javascript`	`false`	Transmitido como está
Qualquer outro valor	`true`	Codificado em Base64 antes de ser passado para a função

Exemplos de mapeamento de solicitação

GET

Solicitação 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 solicitação via CLI (substitua https://example.cn-hangzhou.fcapp.run pela URL da sua função):

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

POST

Solicitação HTTP Objeto de evento

Solicitação 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 solicitação via CLI (substitua https://example.cn-hangzhou.fcapp.run pela URL da sua função):

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

Para forçar a codificação Base64 do corpo da solicitação, defina Content-Type como application/x-www-form-urlencoded .

Estrutura da resposta

Formato

A saída da sua função é analisada em uma estrutura de resposta antes de ser mapeada para a resposta HTTP:

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

Lógica de mapeamento

O Function Compute mapeia a saída da sua função para a resposta HTTP com base na validade do JSON e na presença do campo statusCode.

**Quando a saída é um JSON válido com statusCode:**

Campo da estrutura de resposta	Resposta HTTP
`statusCode`	Código de status
`headers["Content-Type"]`	Cabeçalho `Content-Type` (padrão `application/json` se ausente)
`body`	Corpo da resposta
`isBase64Encoded`	Indica se o corpo deve ser decodificado de Base64 antes do envio (padrão `false` se ausente)

**Quando a saída é um JSON válido sem statusCode ou não é JSON:**

O Function Compute utiliza os seguintes padrões:

Campo	Valor padrão
`statusCode`	`200`
`Content-Type`	`application/json`
`body`	Saída da função como está
`isBase64Encoded`	`false`

Exemplos de mapeamento de resposta

Os exemplos a seguir mostram como a saída da função flui através da análise até a resposta HTTP final.

Saída para uma resposta de string

Saída da função	Estrutura de resposta analisada	Resposta HTTP (recebida pelo 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!`

Saída para uma resposta JSON

Saída da função	Estrutura de resposta analisada	Resposta HTTP (recebida pelo 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!"}`

Saída para uma resposta personalizada

Saída da função	Estrutura de resposta analisada	Resposta HTTP (recebida pelo 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!"}`

Decodificação Base64

Se sua função retornar um JSON válido com isBase64Encoded definido como true, o Function Compute decodifica o body de Base64 antes de mapeá-lo para o corpo da resposta HTTP. Se a decodificação falhar, o Function Compute retorna o valor de body diretamente, sem relatar erro.

Cabeçalhos de resposta

O Function Compute adiciona automaticamente o cabeçalho X-Fc-Request-Id a todas as respostas. Esse cabeçalho identifica exclusivamente a solicitação e é útil para rastrear logs e diagnosticar erros. Além de X-Fc-Request-Id, o Function Compute não adiciona nenhum outro cabeçalho de resposta por padrão.

Aviso

Cabeçalhos personalizados com o prefixo X-Fc- não são suportados. Os seguintes cabeçalhos são reservados pelo Function Compute e ignorados caso sejam retornados pela sua função:

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

Tratamento de erros

As invocações via gatilho HTTP e as invocações diretas de API tratam os erros de função de maneira diferente.

Tipo de invocação	Comportamento de erro	Código de status HTTP
Invocação direta de API	Mensagem de erro retornada no corpo da resposta	`200`
Gatilho HTTP (URL da função)	Mensagem de erro oculta; `Internal Server Error` retornado	`502`

Por exemplo, uma invocação direta de API que encontra um ModuleNotFoundError em Python retorna os seguintes detalhes de erro:

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

Quando uma função invocada via gatilho HTTP encontra um erro, o cliente recebe uma resposta como:

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

Utilize o valor de X-Fc-Request-Id para consultar os detalhes completos do erro nos logs de invocação da sua função.

Tópicos relacionados

Se você estiver escrevendo código de função para um runtime integrado, consulte a documentação do handler para sua linguagem: