You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@openwhisk.apache.org by GitBox <gi...@apache.org> on 2018/08/23 20:36:52 UTC
[GitHub] pritidesai commented on a change in pull request #84: Updating
Readme to include more usage documentation
pritidesai commented on a change in pull request #84: Updating Readme to include more usage documentation
URL: https://github.com/apache/incubator-openwhisk-runtime-nodejs/pull/84#discussion_r212448837
##########
File path: README.md
##########
@@ -17,63 +17,353 @@
#
-->
-# Apache OpenWhisk runtimes for nodejs
+# Apache OpenWhisk runtimes for Node.js
[](http://www.apache.org/licenses/LICENSE-2.0)
[](https://travis-ci.org/apache/incubator-openwhisk-runtime-nodejs)
-### Give it a try today
-To use as a docker action for Node.js 6
+The basics of creating OpenWhisk action is explained in core OpenWhisk repo under [OpenWhisk Actions](https://github.com/apache/incubator-openwhisk/blob/master/docs/actions.md#the-basics). The following sections walks you through creating and invoking a simple JavaScript action such as `hello world`. Then add parameters to an action and invoke that action with parameters, followed by setting default parameters and invoking action. Finally, demonstrate how to bundle multiple JavaScript files and third party modules.
+
+### Create OpenWhisk Actions using JavaScript
+
+1. Create a JavaScript file named `hello.js` with the following content:
+
+```javascript
+function main() {
+ return { msg: 'Hello world' };
+}
+```
+
+2. Create an action using `hello.js` with `wsk` CLI:
+
+```bash
+$ wsk action create hello hello.js
+ok: created action hello
```
-wsk action update myAction myAction.js --docker openwhisk/nodejs6action
+
+3. Invoke the `hello` action as a blocking activation:
+
+```bash
+$ wsk action invoke hello --blocking
+{
+ "result": {
+ "payload": "Hello world"
+ },
+ "status": "success",
+ "success": true
+}
+```
+
+### Node.js Runtime Enviornment
+
+JavaScript actions can be executed in Node.js version 6 or Node.js version 8. Currently actions are executed by default in a Node.js version 6 environment.
+
+The `wsk` CLI automatically infers the type of the action by using the source file extension.
+For `.js` source files, the action runs by using a **Node.js** runtime. You may specify
+the Node.js runtime to use by explicitly specifying the parameter `--kind nodejs:6` or `--kind nodejs:8`.
+
+### Actions with Parameters
+
+Parameters can be passed to the action when it is invoked.
+
+1. Create `hello.js` file with the following content:
+
+```javascript
+function main(params) {
+ var name = params.name || 'stranger';
+ var place = params.place || 'somewhere';
+ return {payload: 'Hello, ' + name + ' from ' + place};
+}
+```
+
+The input parameters are passed as a JSON object parameter to the main function.
+
+2. Update the action:
+
+```bash
+$ wsk action update hello hello.js
+```
+
+3. Parameters can be provided explicitly on the command-line by using `--param` flag:
+
+```bash
+$ wsk action invoke --result hello --param name Dorothy --param place Kansas
+```
+
+This produces the result:
+
+```bash
+{
+ "payload": "Hello, Dorothy from Kansas"
+}
+```
+
+[Working with Parameters](https://github.com/apache/incubator-openwhisk/blob/master/docs/parameters.md#working-with-parameters) in core OpenWhisk demonstrates few more ways to specify parameters for an action during it's invocation.
+
+### Hello as a OpenWhisk Docker Action
+
+To create `hello` as a docker action for Node.js 6
+
+```
+wsk action update hello hello.js --docker openwhisk/nodejs6action
+```
+
+To create `hello` as a docker action for Node.js 8
+
+```
+wsk action update hello hello.js --docker openwhisk/action-nodejs-v8
+```
+
+This works on any deployment of Apache OpenWhisk.
+
+### Beyond Hello - JavaScript Promise for an External API
+
+This example shows how to call an external API like a Yahoo Weather service to get the current weather conditions at a specific location.
+
+1. Create `weather.js` with the following content:
+
+```javascript
+function main(params) {
+ var location = params.location || 'Vermont';
+ var url = 'https://query.yahooapis.com/v1/public/yql?q=select item.condition from weather.forecast where woeid in (select woeid from geo.places(1) where text="' + location + '")&format=json';
+ var request = require("request");
+
+ return new Promise(function (resolve, reject) {
+ request.get(url, function (error, response, body) {
+ console.log("we are inside the request");
+ if (error) {
+ console.log(error);
+ reject(error);
+ } else {
+ if (response.statusCode == 200) {
+ var condition = JSON.parse(body).query.results.channel.item.condition;
+ var conditionText = condition.text;
+ var conditionTemp = condition.temp;
+ var output = 'It is ' + conditionTemp + ' degrees in ' + location + ' and ' + conditionText + '!';
+ resolve({msg: output});
+ } else {
+ reject({
+ statusCode: response.statusCode,
+ response: body
+ });
+ }
+ }
+ });
+ });
+}
+```
+
+Note that the action in this example uses the JavaScript request library to make an HTTP request to the Yahoo Weather API, and extracts fields from the JSON result. See the [Node.js version 6 Envionment](#nodejs-version-6-enviornment) for the Node.js packages available in the runtime environment.
+
+This example also shows the need for asynchronous actions. The action returns a Promise to indicate that the result of this action is not available yet when the function returns. Instead, the result is available in the request callback after the HTTP call completes, and is passed as an argument to the resolve() function.
+
+A call to `reject()` can be used to reject the Promise and signal that the activation has completed abnormally.
+
+2. Create an action from the `weather.js` file:
+
+```bash
+wsk action create weather weather.js
```
-To use as a docker action for Node.js 8
+
+3. Use the following command to run the action, and observe the output:
+
+```bash
+wsk action invoke --result weather --param location "Brooklyn, NY"
```
-wsk action update myAction myAction.js --docker openwhisk/action-nodejs-v8
+
+Using the `--result` flag means that the value returned from the action is shown as output on the command-line:
+
+```bash
+{
+ "msg": "It is 28 degrees in Brooklyn, NY and Cloudy!"
+}
```
-This works on any deployment of Apache OpenWhisk
-### To use on deployment that contains the rutime as a kind
-To use as a kind action using Node.js 6
+### Beyond Hello - JavaScript Promise for Queuing Asynchronous Actions
+
+You can add `then` together to transform values or run additional asynchronous actions one after another.
+
+The following example demonstrates multiple concpts:
+
+* Usage of `wsk.actions.invoke` to invoke any OpenWhisk action which returns `Promise`.
+* Adding `then` to replace `Hello` with `Goodbye` in the greeting message returned from action invoked inside of the `Promise`.
+
+1. Create `goodbye.js` with the following content:
+
+```javascript
+var openwhisk = require('openwhisk');
+
+function main(params) {
+ var wsk = openwhisk({ignore_certs: params.ignore_certs || false});
+ var wsk = openwhisk();
+ return wsk.actions.invoke({
+ actionName: '/whisk.system/samples/greeting',
+ params: {
+ name: params.name,
+ place: params.place
+ },
+ blocking: true
+ }).then(activation => {
+ console.log('activation:', activation);
+ var payload = activation.response.result.payload.toString();
+ var output = payload.replace("Hello", "Goodbye");
+ return { msg: output };
+ });
+}
```
-wsk action update myAction myAction.js --kind nodejs:6
+
+2. Create an action from the `goodbye.js` file:
+
+```bash
+wsk action create goodbye goodbye.js
```
-To use as a kind action using Node.js 8
+
+3. Use the following command to run the action, and observe the output:
+
+```bash
+wsk action invoke --result goodbye --param name "Amy" --param location "Paris"
```
-wsk action update myAction myAction.js --kind nodejs:8
+Returns:
+
+```bash
+{
+ "msg": "Goodbye, Amy from Paris!"
+}
```
-### Local development
-For Node.js 6
+### Node.js version 6 Enviornment
Review comment:
thanks @rabbah yup, I am evaluating how to separate these docs, this PR is first step towards adding new material. I am working on a separate PR to address splitting up docs.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services