HTTP Functions

HTTP Functions are used when you want to directly invoke your function via HTTP(S). To allow for specific HTTP semantics, the signature of an HTTP function takes HTTP-specific arguments: request and response.

The request parameter represents the HTTP request that was sent to the function, and the response parameter represents the HTTP response that will be returned to the caller. These parameters have properties of ExpressJS Request and Response objects, which should be used to extract and return data.

Example:

Node.js

/**
 * Responds to any HTTP request that can provide a "message" field in the body.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
exports.helloWorld = function helloWorld (req, res) {
  if (req.body.message === undefined) {
    // This is an error case, as "message" is required
    res.status(400).send('No message defined!');
  } else {
    // Everything is ok
    console.log(req.body.message);
    res.status(200).end();
  }
};

The following command shows how to call the function and pass it a simple message:

curl -X POST -H "Content-Type:application/json"  -d '{"message":"hello world!"}' YOUR_HTTP_TRIGGER_ENDPOINT

The body of the request is automatically parsed based on the content-type and populated in the body of the request object. For example:

Content Type Request Body Behavior
application/json '{"name":"John"}' request.body.name equals 'John'
application/octet-stream 'my text' request.body equals '6d792074657874' (see Node.js Buffer docs)
text/plain 'my text' request.body equals 'my text'
application/x-www-form-urlencoded 'name=John' request.body.name equals 'John'

This parsing is done by the following body parsers:

Example:

Node.js

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
exports.helloContent = function helloContent (req, res) {
  let name;

  switch (req.get('content-type')) {
    // '{"name":"John"}'
    case 'application/json':
      name = req.body.name;
      break;

    // 'John', stored in a Buffer
    case 'application/octet-stream':
      name = req.body.toString(); // Convert buffer to a string
      break;

    // 'John'
    case 'text/plain':
      name = req.body;
      break;

    // 'name=John'
    case 'application/x-www-form-urlencoded':
      name = req.body.name;
      break;
  }

  res.status(200).send(`Hello ${name || 'World'}!`);
};

Suppose your function is called with the following request:

curl -X POST -H "Content-Type:application/json" -H "X-MyHeader: 123" YOUR_HTTP_TRIGGER_ENDPOINT?foo=baz -d '{"text":"something"}'

then the sent data would be materialized under:

Property/Method Value
request.method "POST"
request.get('x-myheader') "123"
request.query.foo "baz"
request.body.text "something"

Handling HTTP Methods

If function needs to handle multiple HTTP methods (GET, PUT, POST, and so on), you can simply inspect the method property of the request. For example:

Node.js

function handleGET (req, res) {
  // Do something with the GET request
  res.status(200).send('Hello World!');
}

function handlePUT (req, res) {
  // Do something with the PUT request
  res.status(403).send('Forbidden!');
}

/**
 * Responds to a GET request with "Hello World!". Forbids a PUT request.
 *
 * @example
 * gcloud alpha functions call helloHttp
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
exports.helloHttp = function helloHttp (req, res) {
  switch (req.method) {
    case 'GET':
      handleGET(req, res);
      break;
    case 'PUT':
      handlePUT(req, res);
      break;
    default:
      res.status(500).send({ error: 'Something blew up!' });
      break;
  }
};

Accessing the Raw Body of an HTTP Request

HTTP request body data accessible via the req.body property is usually parsed according to its type. For example, body payloads with the type application/json are parsed and provided as a JSON document. In cases where you need access to the raw (unparsed) bytes of the request body, for example, if you're generating cryptographic signatures, you can access a byte buffer using the req.rawBody property. This property will be a Node.js Buffer object.

For example:

/**
 * Accesses the raw (unparsed) body.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
exports.bodyToBase64 = function bodyToBase64 (req, res) {
    // Just send back the raw body as a base64 encoded string
    if(req.rawBody) {
        res.send(req.rawBody.toString('base64'));
    } else {
        res.status(400).send(`No body in request`);
    }
};

Next steps

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Functions Documentation