Quickstart
A quick public service announcement
We now have an API for managing Functions & Asset deployment. Functions & Assets created via the existing Functions UI continue to work as normal. Functions and Assets created via Functions(Classic) and Assets(Classic) are not available via the API. And vice versa: Functions & Assets created via the API aren't available in the Functions(Classic) and Assets(Classic) interface.
Quickest possible start:
If you want to quickly deploy some functions/assets from the command line, you can do so with our CLI and a plugin we've written:
npm install twilio-cli -g twilio plugins:install @twilio-labs/plugin-serverless twilio login twilio serverless:init example cd example twilio serverless:start <do awesome code> twilio serverless:deploy Another cool thing to try after init: twilio serverless:new -- gives you a templated function with code pre-written!
To learn more, visit the Serverless Toolkit documentation. If you are having trouble installing the CLI, check out the CLI docs.
If you want to work through the underlying API (for example if you want to write your own deployment tools), keep following this quickstart.
Get an overview of the API and the Serverless Toolkit by watching our overview video from Twilio Signal 2019:
Great. Let's have a look at how to deploy a single function via the API.
Deploying a single function
Create a Service
First, we'll create a Service, which serves as our container for the environments we set up.
The UniqueName will form part of your domain name, so choose carefully.
We'll get back a Service SID, in the format ZSxxx
.
Create an Environment
We'll use that Service SID, to create a "dev" Environment next.
This will give us an empty environment, e.g. demo-X4HX-dev.twil.io
. To see the domain name for your environment, you can fetch your environment using the ZExxx
SID output from the prior code sample.
Create a Function
Now let's create our Function. We create the Function at the service level, not inside a particular environment (we'll deploy our function to an environment later on). Also, we only set the name for the function at this step. We'll choose a path, visibility, and upload the code for the function in later steps.
Save the Function SID for the next step where we create a Version.
With a Function created, we're ready to create our first Version. Versions of Functions or Assets are where you add the path, visibilty (public, protected or private), and the file content itself. Versions are created at a different URL to allow uploading the file content.
First, we need a function file to upload. Lets write a simple function that decides the fate of the universe:
exports.handler = function(context, event, callback) { const sparedByThanos = Math.random() > 0.5; callback(null, { sparedByThanos, quote: 'You should have gone for the head.' }); };
Now we have a function worth uploading. Save this as a file on your computer named firstfunc.js
.
Now we can actually upload that file. The create API action is not currently represented in the helper libraries, so you have to do a manual file upload in the language of your choice. See examples below.
With that upload complete, save the resulting SID for the newly created Version.
Create a Build
Now, we need to to create a Build. A Build will compile Function and Asset Versions into a single, deployable package. It lives in the Twilio cloud, so you just need the Build SID to reference it -- there's no files to keep track of.
You'll receive a return straight away, but note that there's a status
property. We need to wait until the status returns completed
before continuing. The best way to handle the status changes is to poll every second or two:
When we have a completed
build, we're ready to deploy.
Create a Deployment
Let's do the final step, associating the Build we just did with the Environment we created at the start of our tutorial. This is called a Deployment.
Your function is now live! You can test it out by going to a URL like https://demo-X4HX-dev.twil.io/thanos
(be sure to replace demo-X4HX-dev.twil.io
with the unique domain name for your Environment, created above).
Adding dependencies
We can specify dependencies when creating a build.
Handling Asset uploads
The pattern we used above for uploading Functions is exactly the same as it for Assets. We create an /Asset
, we create the /Assets/[AssetSid]/Versions
via a POST to the serverless-uploads.twilio.com domain, and then we add the "AssetVersions"
we want to include in the Build alongside FunctionVersions and any dependencies we might need.
What's next?
Definitely take a look at the API reference section for all of the API resources below. You might be particularly interested in Variables to allow setting environment variables for a given Environment.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.