HTTP trigger

Note:

1. The function interface for setting the HTTP trigger is different from the common function interface. For more information, see HTTP trigger interface form.

HTTP triggers are a common type of triggers used in Function Compute to invoke functions when an HTTP request is sent. With HTTP triggers, you can quickly construct web services. HTTP triggers support HEAD, POST, PUT, GET, and DELETE method triggers.

Compared to API Gateway triggers, which are difficult for new users, HTTP triggers offer the following advantages:

• The easier learning and debugging processes help you quickly implement web services and APIs by using Function Compute.
• You can use the HTTP testing tools you are familiar with to verify the functionality and performance of Function Compute.
• Requests are processed in fewer stages. HTTP triggers support more efficient request and response formats and are not encoded or decoded into JSON strings. Therefore, the performance is improved.
• You can easily connect to other services that support webhooks, such as Content Delivery Network (CDN) back-to-origin and Message Notification Service (MNS).

Note:

1. You can bind a custom domain name to map different HTTP access paths to HTTP functions. You can also use API Gateway by selecting the HTTP service as the backend trigger type and configuring an HTTP function as the backend service address for the same purpose.
2. For security, when you use the default domain name aliyuncs.com of Function Compute, the server inserts the content-disposition: attachment field into the response header. This field is used to download the returned result in the browser as an attachment. To remove this limit, set a custom domain name.

This topic describes the following aspects of HTTP triggers:

• HTTP trigger interface format
• HTTP trigger configuration
• HTTP trigger examples
• Troubleshooting

Limits

• Once an HTTP trigger is set for a function, the trigger type cannot be changed for the function.

• A function can have only one HTTP trigger.

• Under version control, only one HTTP trigger can be configured for each (version or alias, function) combination.

  • For example, an HTTP trigger can be configured for alias 1 that directs to version 1 (version 1, function 1), and an HTTP trigger can be configured for (alias 1, function 1).

• Note: The following fields in the Request Headers key are ignored. Function Compute contains these fields by default and does not support custom settings. Keys that start with x-fc- are also ignored.

• accept-encoding

• connection

• keep-alive

• proxy-authorization

• te

• trailer

• transfer-encoding

• Note: The following fields in the Response Headers key are ignored. Function Compute contains these fields by default and does not support custom settings. Keys that start with x-fc- are also ignored.

• connection

• content-length

• content-encoding

• date

• keep-alive

• proxy-authenticate

• server

• trailer

• transfer-encoding

• upgrade

• content-disposition: attachment (This field is added after the custom domain name is set.)

Request limits

If the following limits are exceeded, the system throws a 400 status code and InvalidArgument error code.

• Header size:The total size of all keys and values in the headers cannot exceed 4 KB.
• Path size:The path size, including all parameters, cannot exceed 4 KB.
• Body size:The size of the HTTP response body cannot exceed 6 MB.

Response limits

If the following limits are exceeded, the system throws a 502 status code and BadResponse error code.

• Header size:The total size of all keys and values in the headers cannot exceed 4 KB.
• Body size:The size of the HTTP response body cannot exceed 6 MB.

HTTP trigger interface format

The function interface for setting the HTTP trigger is different from that of Function Compute. Currently, Node.js runtime, Python runtime, PHP runtime, and Java runtime are supported.

For more information about the interface format, see:

• Node.js functions with HTTP triggers configured
• Python functions with HTTP triggers configured
• PHP functions with HTTP triggers configured
• C# functions with HTTP triggers configured
• Java functions with HTTP triggers configured

The following figure shows common functions (left) and functions with HTTP triggers (right). If you are still using common interfaces after setting HTTP triggers, correct this promptly.

Node.js:

Python:

Configure an HTTP trigger

Assemble the HTTP trigger URL

You can send an HTTP request to the following URL to invoke the function:

// A common HTTP trigger URL
<account_id>.<region>.fc.aliyuncs.com/<version>/proxy/<serviceName>/<functionName>/[action?queries]
// The HTTP trigger URL under version control
<account_id>.<region>.fc.aliyuncs.com/<version>/proxy/<serviceName>.<qualifier>/<functionName>/[action?queries]

• “version” specifies the version of the Function Compute API. For more information, see version.
• “serviceName” specifies the trigger-directed service. “qualifier” specifies the version or alias of the trigger-directed service. The connector is period (.). For more information, see Version control. When “version” is set, the URL does not specify a “qualifier”, and the request is processed by the latest version.
• “queries” is the query parameter of the HTTP request.

Example:

123456.cn-shanghai.fc.aliyuncs.com/2016-08-15/proxy/serviceName/functionName/action?hello=world

HTTP trigger configuration

HTTP trigger configuration format:

{
    "authType" : "anonymous",
    "methods" : ["GET", "POST"]
}

The HTTP trigger configuration has two key fields:

• authType: the authentication type with these values:

  • anonymous: The server does not require identity authentication and supports anonymous access. The system is of low security.
    Example:
    

    curl "<account-id>.<region>.fc.aliyuncs.com/2016-08-15/proxy/serviceName/functionName/action?hello=world"

  • function: The server requires identity authentication and does not support anonymous access. The system is highly secure. Requests must pass signature authentication and HTTP request headers must contain Authorization and Date. The Date parameter is in UTC format and is used to calculate the signature. The server uses the Date value to calculate the signature and compares it with the transmitted Authorization value. The request passes the authentication only if the signatures match and the difference between the current time and the Date value is less than 15 minutes.

• methods: The access methods supported by the HTTP trigger:
  • HEAD: HTTP HEAD method
  • GET: HTTP GET method
  • POST: HTTP POST method
  • PUT: HTTP PUT method
  • DELETE: HTTP DELETE method

Example 1 Console operation

This example shows how to create an HTTP trigger in the console.

For information about triggers and how to create them, see Introduction to triggers and Create a trigger.

Step 1 Configure an HTTP trigger

You can select and configure a trigger when or after creating a function.

Configure a trigger when creating a function

1. Log on to the Function Compute console.

2. Select a region, such as China (Shanghai).

3. Select a service and function in the left-side navigation pane.

4. Click Create Function.

5. On the Create Function page, click HTTP Function.

6. Create a function and set Service Name, Function Name, Function Description, and Runtime. Configure an HTTP trigger according to the following figure, and then click OK.
   

7. On the Code Execution page, select In-line Edit and paste the following Node.js runtime sample code for the HTTP function.

var getRawBody = require('raw-body')
module.exports.handler = function (request, response, context) {
    // get requset header
    var reqHeader = request.headers
    var headerStr = ' '
    for (var key in reqHeader) {
        headerStr += key + ':' + reqHeader[key] + '  '
    };
    // get request info
    var url = request.url
    var path = request.path
    var queries = request.queries
    var queryStr = ''
    for (var param in queries) {
        queryStr += param + "=" + queries[param] + '  '
    };
    var method = request.method
    var clientIP = request.clientIP
    // get request body
    getRawBody(request, function (err, data) {
        var body = data
        // you can deal with your own logic here
        // set response
        // var respBody = new Buffer('requestURI' + requestURI + ' path' + path +  ' method' + method + ' clientIP' + clientIP)
        var respBody = new Buffer('requestHeader:' + headerStr + '\n' + 'url: ' + url + '\n' + 'path: ' + path + '\n' + 'queries: ' + queryStr + '\n' + 'method: ' + method + '\n' + 'clientIP: ' + clientIP + '\n' + 'body: ' + body + '\n')
        // var respBody = new Buffer( )
        response.setStatusCode(200)
        response.setHeader('content-type', 'application/json')
        response.send(respBody)
    })
};

1. Click Save.

Step 2 Debug the trigger

1. Select the target function. On the page that appears, click the Code tab and scroll down the page.

2. Click the Params tab and enter your key-value pairs. Then, the key-value pairs are automatically added to the HTTP URL.

   

3. Click the Header tab to set the request header and enter your key-value pairs. When authentication is required, the request header on this tab automatically contains the Date and Authorization keys.

4. Click Invoke.

Example 2 (Recommended) Create an HTTP trigger by using Fun

Fun supports HTTP triggers and allows you to create and update function triggers. The following steps show how to use Fun to configure an HTTP trigger.

First, create an index.js file in the root directory of your project.

var getRawBody = require('raw-body')
module.exports.handler = function (request, response, context) {    
    // get request body
    getRawBody(request, function (err, body) {
        var respBody = {
            headers: request.headers,
            url: request.url,
            path: request.path,
            queries: request.queries,
            method: request.method,
            clientIP: request.clientIP,
            body: body.toString()
        };
        response.setStatusCode(200);
        response.setHeader('content-type', 'application/json');
        response.send(JSON.stringify(respBody, null, 4));
    });
};

Configure related services. Create a template.yml file in the root directory of your project:

ROSTemplateFormatVersion: '2015-09-01'
Transform: 'Aliyun::Serverless-2018-04-03'
Resources:
  FunDemo:
    Type: 'Aliyun::Serverless::Service'
    httpdemo:
      Type: 'Aliyun::Serverless::Function'
      Properties:
        Handler: index.handler
        CodeUri: . /
        Description: 'http trigger demo!'
        Runtime: nodejs8
      Events:
        http-test:
          Type: HTTP
          Properties:
            AuthType: ANONYMOUS
            Methods: ['GET', 'POST', 'PUT']

After compiling the code and template file, run the fun deploy command to deploy services online with one click.

$ fun deploy
using region: cn-hangzhou
using accountId: ***********3557
using accessKeyId: ***********r3Ra
using timeout: 300
Waiting for service FunDemo to be deployed...
    Waiting for function httpdemo to be deployed...
        Waiting for packaging function httpdemo code...
        package function httpdemo code done
        Waiting for HTTP trigger http-test to be deployed...
        methods: [ 'GET', 'POST', 'PUT' ]
        url: https://1911504709953557.cn-hangzhou.fc.aliyuncs.com/2016-08-15/proxy/FunDemo/httpdemo/
        function httpdemo deploy success
    function FunDemo deploy success
service FunDemo deploy success

Open a browser, and enter the address https://1911504709953557.cn-hangzhou.fc.aliyuncs.com/2016-08-15/proxy/FunDemo/httpdemo/ to trigger the function execution. For HTTP triggers, the server inserts the content-disposition: attachment field into the response header. This field is used to open the returned result in the browser as an attachment. This field cannot be overridden and is immune to the use of a custom domain name. For more information, see Function Compute FAQ.

If the HTTP trigger configuration is modified, run the fun deploy command again.

To step through and run functions with HTTP triggers locally, see Guidelines for Function Compute Development - Local Running and Debugging of HTTP Triggers.

For more configuration rules, see here.

For more Fun tutorials, click here.

Example 3 Create an HTTP trigger through SDK programming

The following example shows how to use the Python SDK to create an HTTP trigger.

Note: The functions that use interfaces with HTTP triggers can be invoked only by sending HTTP requests to specified addresses, but not by using the invoke_function method in SDKs.

Prerequisites

• You have deployed the Python environment.
• You have installed the Python SDK for Function Compute. pip install aliyun-fc2 To obtain the Python SDK for Function Compute, run pip install aliyun-fc2 on your local device.

Procedure

1. Compile a function in Function Compute. Copy the sample code and paste it to main.js the main.js file in the code folder.

2. Create the file create_http_trigger.py, create_http_trigger.py and copy and paste the following Python code to the file.

import fc2
import os
def main():
    service_name = "http_trigger_service"
    func_name = "test_http_trigger_node"
    endpoint = os.getenv("FC_ENDPOINT")
    url = "%s/2016-08-15/proxy/%s/%s" % (endpoint, service_name, func_name)
    print url
    fc_client = fc2.Client(
            endpoint=endpoint,
            accessKeyID=os.getenv("ACCESS_KEY_ID"),
            accessKeySecret=os.getenv("ACCESS_KEY_SECRET"),
            Timeout=5)
    fc_client.create_service(service_name)
    fc_client.create_function(service_name, func_name, "nodejs6", "main.handler", codeDir='./code')
    trigger_config = {
            "authType" : "anonymous",
            "methods" : ["GET", "POST"],
    }
    fc_client.create_trigger(service_name, func_name, "trigger_on_echo", "http", trigger_config, "dummy_arn", "")
main()

1. Run python create_http_trigger.py python create_http_trigger.py to create an HTTP trigger.

2. Send an HTTP request to invoke the function.

   Example:

   curl -v  "<account-id>.<region>.fc.aliyuncs.com/2016-08-15/proxy/http_trigger_service/test_http_trigger_node/action"

   The result is as follows:

Example 3: Initializer interface

When using an HTTP trigger, you can also apply the initialization logic to the initializer function. When the initializer function and HTTP trigger are used in combination, they can maintain their original structures without any special changes. For more information about the initializer interface, see the initializer entry definition.

The Python runtime sample code is as follows:

# -*- coding: utf-8 -*-
import logging
HELLO_WORLD = b"Hello world!\n"
def initializer(context):
    logger = logging.getLogger()
    logger.info("initialized")
def handler(environ, start_response):
    logger = logging.getLogger()
    logger.info("run after initialized")
    context = environ['fc.context']
    request_uri = environ['fc.request_uri']
    for k, v in environ.items():
      if k.startswith("HTTP_"):
        # process custom request headers
        pass
    # do something here
    status = '200 OK'
    response_headers = [('Content-type', 'text/plain')]
    start_response(status, response_headers)
    return [HELLO_WORLD]

Example 4 Create an HTTP trigger by using fcli

The following example shows how to create an HTTP trigger in the Node.js 6 runtime by using the command-line tool fcli:

• Create the http_echo and http_echo/code directories.
• Paste the code in http_echo/code/index.js and create config.json.

{
"triggerConfig": {
"authType" : "anonymous",
"methods" : ["GET", "POST"]
}
}

• Run the following command to create the test_echo function in the test_service service:

fcli function create -s test_service -f test_echo --runtime nodejs6 --code-dir code --handler index.handler

• Run the following command to retrieve all trigger information about the test_echo function:

fcli trigger list -s test_service -f test_echo

• Run the following command to create an HTTP trigger named test_trigger_name in the test_echo function of the test_service service:

fcli trigger create -s test_service -f test_echo --trigger-name test_trigger_name --type http --source-arn dummy --config config.json

• Run the following command to update information about the test_trigger_name trigger for test_echo:

fcli trigger update -s test_service -f test_echo -t test_trigger_name --trigger-config config.json

• Run the following command to delete the test_trigger_name trigger from test_echo:

fcli trigger delete -s test_service -f test_echo -t test_trigger_name

• For more information, watch this video (commands can be copied):

Troubleshooting

The main types of errors are request errors and function errors. A request error occurs when the request sent by the user does not comply with the standard and the response contains a 4xx status code. A function error occurs when the function is improperly programmed and a 5xx status code is returned. Scenarios in which request and function errors may occur are described in the following table to facilitate your quick troubleshooting.

If the problem persists, please contact us.