When working with serverless actions, data is supplied by adding parameters to the actions; these are in the parameter declared as an argument to the main serverless function. All data arrives this way and the values can be set in a few different ways. The first option is to supply parameters when an action or package is created (or updated). This approach is useful for data that stays the same on every execution, equivalent to environment variables on other platforms, or for default values that might be overridden at invocation time. The second option is to supply parameters when the action is invoked - and this approach will override any parameters already set.
This page outlines how to configure parameters when deploying packages and actions, and how to supply parameters when invoking an action. There is also information on how to use a file to store the parameters and pass the filename, rather than supplying each parameter individually on the command-line.
- Use parameters in the action. For example, create 'hello.js' file with the following content:
The input parameters are passed as a JSON object parameter to the
main function. Notice how the
place parameters are retrieved from the
params object in this example.
- Update the action so it is ready to use:
- Parameters can be provided explicitly on the command-line, or by supplying a file containing the desired parameters
To pass parameters directly through the command-line, supply a key/value pair to the
This produces the result:
Notice the use of the
--result option: it implies a blocking invocation where the CLI waits for the activation to complete and then displays only the result. For convenience, this option may be used without
--blocking which is automatically inferred.
Additionally, if parameter values specified on the command-line are valid JSON, then they will be parsed and sent to your action as a structured object. For example, if we update our hello action to:
Now the action expects a single
person parameter to have fields
place. If we invoke the action with a single
person parameter that is valid JSON:
The result is the same because the CLI automatically parses the
person parameter value into the structured object that the action now expects:
Actions can be invoked with multiple named parameters. Recall that the
hello action from the previous example expects two parameters: the name of a person, and the place where they're from.
Rather than pass all the parameters to an action every time, you can bind certain parameters. The following example binds the place parameter so that the action defaults to the place "Kansas":
- Update the action by using the
--paramoption to bind parameter values, or by passing a file that contains the parameters to
To specify default parameters explicitly on the command-line, provide a key/value pair to the
- Invoke the action, passing only the
nameparameter this time.
Notice that you did not need to specify the
place parameter when you invoked the action. Bound parameters can still be overwritten by specifying the parameter value at invocation time.
- Invoke the action, passing both
placevalues, and observe the output:
Despite a parameter set on the action when it was created/updated, this is overridden by a parameter that was supplied when invoking the action.
Parameters can be set at the package level, and these will serve as default parameters for actions unless:
- The action itself has a default parameter.
- The action has a parameter supplied at invoke time, which will always be the "winner" where more than one parameter is available.
The following example sets a default parameter of
name on the
MyApp package and shows an action making use of it.
- Create a package with a parameter set:
- Create an action in this package:
- Invoke the action, and observe the default package parameter in use:
It's also possible to put parameters into a file in JSON format, and then pass the parameters in by supplying the filename with the
param-file flag. This works for both packages and actions when creating/updating them, and when invoking actions.
- As an example, consider the very simple "hello" example from earlier. Using
hello.jswith this content:
- Update the action with the updated contents of
- Create a parameter file called
parameters.jsoncontaining JSON-formatted parameters:
- Use the
parameters.jsonfilename when invoking the action, and observe the output
Large portions of this page is copied from the Apache OpenWhisk documentation on April 23rd 2021 - where there have been customisations to match Hypi's deployment this has been noted. Apache OpenWhisk and the Apache name are the property of the Apache Foundation and licensed under the Apache V2 license .