Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id A987B200D14 for ; Tue, 3 Oct 2017 23:44:21 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id A77A31609BD; Tue, 3 Oct 2017 21:44:21 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 275071609DE for ; Tue, 3 Oct 2017 23:44:20 +0200 (CEST) Received: (qmail 65236 invoked by uid 500); 3 Oct 2017 21:44:19 -0000 Mailing-List: contact commits-help@openwhisk.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@openwhisk.apache.org Delivered-To: mailing list commits@openwhisk.apache.org Received: (qmail 65227 invoked by uid 99); 3 Oct 2017 21:44:19 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 03 Oct 2017 21:44:19 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id AA6A88193F; Tue, 3 Oct 2017 21:44:18 +0000 (UTC) Date: Tue, 03 Oct 2017 21:44:18 +0000 To: "commits@openwhisk.apache.org" Subject: [incubator-openwhisk-wskdeploy] branch master updated: Programming Guide - part 10 (#584) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Message-ID: <150706705863.24847.17241421211733557590@gitbox.apache.org> From: houshengbo@apache.org X-Git-Host: gitbox.apache.org X-Git-Repo: incubator-openwhisk-wskdeploy X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Oldrev: 77236cb4f29ba5958c9aa44a134868071896a40a X-Git-Newrev: 012df82cff886450ec0e23fe568b30b9bf9542d1 X-Git-Rev: 012df82cff886450ec0e23fe568b30b9bf9542d1 X-Git-NotificationType: ref_changed_plus_diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated archived-at: Tue, 03 Oct 2017 21:44:21 -0000 This is an automated email from the ASF dual-hosted git repository. houshengbo pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-wskdeploy.git The following commit(s) were added to refs/heads/master by this push: new 012df82 Programming Guide - part 10 (#584) 012df82 is described below commit 012df82cff886450ec0e23fe568b30b9bf9542d1 Author: Matt Rutkowski AuthorDate: Tue Oct 3 16:44:17 2017 -0500 Programming Guide - part 10 (#584) * Initial markdown and example code for env. var. example. * Initial markdown and example code for env. var. example. * Initial markdown and example code for env. var. example. * Initial markdown and example code for env. var. example. * Initial markdown and example code for env. var. example. * Initial markdown and example code for env. var. example. * Initial markdown and example code for env. var. example. * Add runtime version example. * Add runtime version example. * Add runtime version example. * Add runtime version example. * Add runtime version example. * Add runtime version example. * Add runtime version example. * Add runtime version example. * Add bottom nav. to all spec. markdown pages. * Add bottom nav. to all spec. markdown pages. * Add bottom nav. to all spec. markdown pages. * Add bottom nav. to all spec. markdown pages. * Add bottom nav. to all spec. markdown pages. * Add bottom nav. to all spec. markdown pages. --- .../manifest_hello_world_env_var_parms.yaml | 14 +++ docs/examples/manifest_hello_world_runtime.yaml | 9 ++ docs/examples/src/hello.py | 19 ++++ docs/programming_guide.md | 4 +- docs/wskdeploy_action_advanced_parms.md | 10 +- docs/wskdeploy_action_env_var_parms.md | 96 +++++++++++++++++++ docs/wskdeploy_action_fixed_parms.md | 5 +- docs/wskdeploy_action_helloworld.md | 4 +- docs/wskdeploy_action_runtime.md | 102 +++++++++++++++++++++ docs/wskdeploy_action_typed_parms.md | 2 +- docs/wskdeploy_example_template.md | 59 ++++++++++++ docs/wskdeploy_sequence_basic.md | 59 ++++++++++++ docs/wskdeploy_triggerrule_basic.md | 2 +- docs/wskdeploy_triggerrule_trigger_bindings.md | 4 +- specification/README.md | 18 ++-- specification/html/spec_actions.md | 16 ++++ specification/html/spec_index.md | 4 +- specification/html/spec_normative_refs.md | 15 +++ specification/html/spec_packages.md | 16 ++++ specification/html/spec_parameters.md | 17 ++++ specification/html/spec_sequences.md | 16 ++++ specification/html/spec_shared_entity_schema.md | 15 +++ specification/html/spec_trigger_rule.md | 16 ++++ specification/html/spec_types.md | 16 ++++ 24 files changed, 513 insertions(+), 25 deletions(-) diff --git a/docs/examples/manifest_hello_world_env_var_parms.yaml b/docs/examples/manifest_hello_world_env_var_parms.yaml new file mode 100644 index 0000000..def3888 --- /dev/null +++ b/docs/examples/manifest_hello_world_env_var_parms.yaml @@ -0,0 +1,14 @@ +# Example: “Hello world” with input values set from environment variables +package: + name: hello_world_package + version: 1.0 + license: Apache-2.0 + actions: + hello_world_env_var_parms: + function: src/hello.js + inputs: + name: $FIRSTNAME + place: + value: ${TOWN}, ${COUNTRY} + outputs: + greeting: string diff --git a/docs/examples/manifest_hello_world_runtime.yaml b/docs/examples/manifest_hello_world_runtime.yaml new file mode 100644 index 0000000..484506d --- /dev/null +++ b/docs/examples/manifest_hello_world_runtime.yaml @@ -0,0 +1,9 @@ +# Example: explicit selection of the NodeJS version 6 runtime +package: + name: hello_world_package + version: 1.0 + license: Apache-2.0 + actions: + hello_world_runtime: + function: src/hello.js + runtime: nodejs@6 diff --git a/docs/examples/src/hello.py b/docs/examples/src/hello.py new file mode 100644 index 0000000..e42c695 --- /dev/null +++ b/docs/examples/src/hello.py @@ -0,0 +1,19 @@ +"""OpenWhisk "Hello world" in Python. + +// Licensed to the Apache Software Foundation (ASF) under one or more contributor +// license agreements; and to You under the Apache License, Version 2.0. +""" + + +def main(dict): + """Hello world.""" + if 'name' in dict: + name = dict['name'] + else: + name = "stranger" + if 'place' in dict: + place = dict['place'] + else: + place = "unknown" + msg = "Hello, " + name + " from " + place + return {"greeting": msg} diff --git a/docs/programming_guide.md b/docs/programming_guide.md index aff2dbf..1e91eee 100644 --- a/docs/programming_guide.md +++ b/docs/programming_guide.md @@ -26,15 +26,15 @@ Each example shows the "code", that is the Package Manifest, Deployment file and - [Creating a minimal Package](wskdeploy_package_minimal.md#packages) - creating a basic package manifest and deploying it. - Action examples - [The "Hello World" Action](wskdeploy_action_helloworld.md#actions) - deploy a "hello world" JavaScript function using a manifest. + - [Setting your Function's runtime](wskdeploy_action_runtime.md#actions) - explicitly set the runtime language and version to deplly your action onto. - [Adding fixed input parameters](wskdeploy_action_fixed_parms.md#actions) - bind fixed values to the input parameters of "hello world". - [Typed Parameters](wskdeploy_action_typed_parms.md#actions) - declare named input and output parameters on an Action with their types. - [Advanced Parameters](wskdeploy_action_advanced_parms.md#actions) - input and output parameter declarations with types, descriptions, defaults and more. + - [Using Environment Variables](wskdeploy_action_env_var_parms.md#actions) - reference values from environment variables and bind them to an Action's input parameters. - Trigger and Rule examples. - [Basic Trigger and Rule](wskdeploy_triggerrule_basic.md#triggers-and-rules) - adding a basic trigger and rule to the advanced Parameter "hello world". - [Binding parameters in a Deployment file](wskdeploy_triggerrule_trigger_bindings.md#triggers-and-rules) - using a deployment file to bind values to a Trigger’s parameters and applying them to a compatible manifest file. - - --- + + + diff --git a/docs/wskdeploy_action_fixed_parms.md b/docs/wskdeploy_action_fixed_parms.md index 506947f..3ff1cd5 100644 --- a/docs/wskdeploy_action_fixed_parms.md +++ b/docs/wskdeploy_action_fixed_parms.md @@ -35,7 +35,7 @@ $ wsk action invoke hello_world_package/hello_world_fixed_parms --blocking ### Result The invocation should return an 'ok' with a response that includes this result: -```sh +```json "result": { "greeting": "Hello, Sam from the Shire" }, @@ -51,6 +51,7 @@ In this example: ### Source code The manifest file for this example can be found here: - [manifest_hello_world_fixed_parms.yaml](examples/manifest_hello_world_fixed_parms.yaml) +- [hello.js](examples/src/hello.js) ### Specification For convenience, the Actions and Parameters grammar can be found here: @@ -65,7 +66,7 @@ For convenience, the Actions and Parameters grammar can be found here:
- + diff --git a/docs/wskdeploy_action_helloworld.md b/docs/wskdeploy_action_helloworld.md index d27a365..3cafee9 100644 --- a/docs/wskdeploy_action_helloworld.md +++ b/docs/wskdeploy_action_helloworld.md @@ -45,7 +45,7 @@ $ wsk action invoke hello_world_package/hello_world --blocking ### Result The invocation should return an 'ok' with a response that includes this result: -```sh +```json "result": { "greeting": "Hello, undefined from undefined" }, @@ -82,7 +82,7 @@ For convenience, the Packages and Actions grammar can be found here: - +
<< previous<< previous Example Index next >>
<< previous Example Indexnext >>next >>
diff --git a/docs/wskdeploy_action_runtime.md b/docs/wskdeploy_action_runtime.md new file mode 100644 index 0000000..a59740d --- /dev/null +++ b/docs/wskdeploy_action_runtime.md @@ -0,0 +1,102 @@ +# Actions + +## Setting your Function's runtime + +In the previous ["Hello world" example](), the ```wskdeploy``` utility used the file extension of the function "hello.js" to select the most current NodeJS runtime. + +In most cases, allowing the utility to select the runtime works well using this implicit method. However, perhaps your code is dependent on a specific version of a language runtime and you want to explicitly set it? + +This example shows how to: +- declare an explicit runtime for your Action's function. + +### Manifest file +#### _Example: explicit selection of the NodeJS version 6 runtime_ +```yaml +package: + name: hello_world_package + version: 1.0 + license: Apache-2.0 + actions: + hello_world_runtime: + function: src/hello.js + runtime: nodejs@6 +``` + +### Deploying + +```sh +$ wskdeploy -m docs/examples/manifest_hello_world_runtime.yaml +``` + +### Invoking +```sh +$ wsk action invoke hello_world_package/hello_world_runtime --blocking +``` + +### Result +The invocation should return an 'ok' with a response that includes this result: + +```json +"result": { + "greeting": "Hello, undefined from undefined" +}, +``` + +### Discussion + +In the above example, +- The value for the '```runtime```' key was a valid name and version supported by OpenWhisk + - Please see the current supported list here: **[Actions - Valid runtime names](../specification/html/spec_actions.md#valid-runtime-names)** + +#### Runtime mismatch for function +If the language runtime you requested is not compatible with the function's language, then you will receive an **error** response when invoking the Action. For example, the following manifest indicates a JavaScript (```.js```) function, but the runtime selected as "```python```": +```yaml +package: + name: hello_world_package + ... + actions: + hello_world_runtime: + function: src/hello.js + runtime: python +``` + +The result would a "failure" with a failed response: +```json +"response": { + "result": { + "error": "The action failed to generate or locate a binary. See logs for details." + }, + "status": "action developer error", + "success": false +``` + +### Source code +The source code for the manifest and JavaScript files can be found here: +- [manifest_hello_world_runtime.yaml](examples/manifest_hello_world_runtime.yaml) +- [hello.js](examples/src/hello.js) + +### Specification +For convenience, the Packages and Actions grammar can be found here: +- **[Actions](../specification/html/spec_actions.md#actions)** +- **[Actions - Valid runtime names](../specification/html/spec_actions.md#valid-runtime-names)** + +### Notes + +- If you use the following curl command, you can see the latest runtimes and version supported by the IBM Cloud Functions platform: + - ```curl -k https://openwhisk.ng.bluemix.net``` + +--- + + + + diff --git a/docs/wskdeploy_action_typed_parms.md b/docs/wskdeploy_action_typed_parms.md index 0ea70e6..f031112 100644 --- a/docs/wskdeploy_action_typed_parms.md +++ b/docs/wskdeploy_action_typed_parms.md @@ -51,7 +51,7 @@ $ wsk action invoke hello_world_package/hello_world_typed_parms --blocking ### Result The invocation should return an 'ok' with a response that includes this result: -```sh +```json "result": { "details": "You have 0 children and are 0 m. tall.", "greeting": "Hello, from " diff --git a/docs/wskdeploy_example_template.md b/docs/wskdeploy_example_template.md new file mode 100644 index 0000000..f9d85c9 --- /dev/null +++ b/docs/wskdeploy_example_template.md @@ -0,0 +1,59 @@ +# Section + +## Title + +This example + +This example: +- TBD + +### Manifest File + +#### _Example: TBD_ +```yaml + +``` + +### Deploying +```sh +$ wskdeploy -m +``` + +### Invoking +```sh +$ wsk action invoke +``` + +### Result +The invocation should return an 'ok' with a response that includes this result: +```json + +``` + +### Discussion +- + +### Source code +The manifest file for this example can be found here: +- + +### Specification +For convenience, the Actions and Parameters grammar can be found here: +- **[Actions](../specification/html/spec_actions.md#actions)** +- **[Parameters](../specification/html/spec_parameters.md#parameters)** + +--- + + + + diff --git a/docs/wskdeploy_sequence_basic.md b/docs/wskdeploy_sequence_basic.md new file mode 100644 index 0000000..6641d76 --- /dev/null +++ b/docs/wskdeploy_sequence_basic.md @@ -0,0 +1,59 @@ +# Sequences + +## Creating a basic Action sequence + +This example + +This example: +- TBD + +### Manifest File + +#### _Example: input and output parameters with explicit types and descriptions_ +```yaml + +``` + +### Deploying +```sh +$ wskdeploy -m +``` + +### Invoking +```sh +$ wsk action invoke +``` + +### Result +The invocation should return an 'ok' with a response that includes this result: +```json + +``` + +### Discussion +- + +### Source code +The manifest file for this example can be found here: +- + +### Specification +For convenience, the Actions and Parameters grammar can be found here: +- **[Sequences](../specification/html/spec_sequences.md#sequences)** +- **[Actions](../specification/html/spec_actions.md#actions)** + +--- + + + + diff --git a/docs/wskdeploy_triggerrule_basic.md b/docs/wskdeploy_triggerrule_basic.md index d5f62cf..9faee55 100644 --- a/docs/wskdeploy_triggerrule_basic.md +++ b/docs/wskdeploy_triggerrule_basic.md @@ -113,7 +113,7 @@ For convenience, the Actions and Parameters grammar can be found here:
- + diff --git a/docs/wskdeploy_triggerrule_trigger_bindings.md b/docs/wskdeploy_triggerrule_trigger_bindings.md index 31f0755..6be8516 100644 --- a/docs/wskdeploy_triggerrule_trigger_bindings.md +++ b/docs/wskdeploy_triggerrule_trigger_bindings.md @@ -71,7 +71,7 @@ $ wsk trigger fire meetPerson #### Result Find the activation ID for the “```hello_world_triggerrule```’ Action that firing the Trigger initiated and get the results from the activation record: -``` +```sh $ wsk activation list 3a7c92468b4e4170bc92468b4eb170f1 hello_world_triggerrule @@ -79,7 +79,9 @@ afb2c02bb686484cb2c02bb686084cab meetPersonRule 9dc9324c601a4ebf89324c601a1ebf4b meetPerson $ wsk activation get 3a7c92468b4e4170bc92468b4eb170f1 +``` +```json "result": { "details": "You have 3 children and are 1.88 m. tall.", "greeting": "Hello, Elrond from Rivendell" diff --git a/specification/README.md b/specification/README.md index 89318bd..fa2a9b3 100644 --- a/specification/README.md +++ b/specification/README.md @@ -11,7 +11,7 @@ In general, the goal of this specification is to evolve a simple grammar to desc # Programming Guide If you want to learn how to write Packages and Applications by example using the specification and deploy them using the ```wskdeploy``` utility, please read the step-by-step guide: -- "[wskdeploy utility by example](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/programming_guide.md#wskdeploy-utility-by-example)" +- "[wskdeploy utility by example](../docs/programming_guide.md#wskdeploy-utility-by-example)" # OpenWhisk Package Specification (HTML) @@ -19,14 +19,14 @@ Portions of the OpenWhisk Packaging Specification, for convenience, are made ava ## Index -- [Parameters](spec_parameters.md#parameters) - grammar, schema and examples for input and output parameters. -- [Parameter Types](spec_types.md#parameter-types) - supported YAML and OpenWhisk Types. -- [Shared Entity Schema](spec_shared_entity_schema.md#shared-entity-schema) - fields that are common among entities in the programming model. -- [Packages](spec_packages.md#packages) - grammar, schema and examples for Packages. -- [Actions](spec_actions.md#actions) - grammar, schema and examples for Actions. -- [Triggers and Rules](spec_trigger_rule.md#triggers-and-rules) - grammar, schema and examples for Triggers and Rules. -- [Sequences](spec_sequences.md#sequences) - shema to compose multiple Actions into a sequence. -- [Normative & Non-normative References](spec_normative_refs.md) +- [Parameters](html/spec_parameters.md#parameters) - grammar, schema and examples for input and output parameters. +- [Parameter Types](html/spec_types.md#parameter-types) - supported YAML and OpenWhisk Types. +- [Shared Entity Schema](html/spec_shared_entity_schema.md#shared-entity-schema) - fields that are common among entities in the programming model. +- [Packages](html/spec_packages.md#packages) - grammar, schema and examples for Packages. +- [Actions](html/spec_actions.md#actions) - grammar, schema and examples for Actions. +- [Triggers and Rules](html/spec_trigger_rule.md#triggers-and-rules) - grammar, schema and examples for Triggers and Rules. +- [Sequences](html/spec_sequences.md#sequences) - shema to compose multiple Actions into a sequence. +- [Normative & Non-normative References](html/spec_normative_refs.md) --- diff --git a/specification/html/spec_actions.md b/specification/html/spec_actions.md index f0e3c71..5599e7a 100644 --- a/specification/html/spec_actions.md +++ b/specification/html/spec_actions.md @@ -347,3 +347,19 @@ Return values from the Action's function are used to construct the HTTP response - **headers**: a JSON object where the keys are header-names and the values are string values for those headers (default is no headers). - **code**: a valid HTTP status code (default is 200 OK). - **body**: a string which is either plain text or a base64 encoded string (for binary data). + + +--- + +
+
<< previous<< previous Example Index next >>
+ + + + + +
Specification Index
+
+ diff --git a/specification/html/spec_index.md b/specification/html/spec_index.md index a0a1366..b50ddf7 100644 --- a/specification/html/spec_index.md +++ b/specification/html/spec_index.md @@ -5,7 +5,7 @@ Portions of the OpenWhisk Packaging Specification, for convenience, are made ava # Programming Guide If you want to learn how to write Packages and Applications using the specification and deploy them using the ```wskdeploy``` utility, please read the step-by-step guide: -- "[wskdeploy utility by example](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/programming_guide.md#wskdeploy-utility-by-example)" +- "[wskdeploy utility by example](../../docs/programming_guide.md#wskdeploy-utility-by-example)" ## Index - [Parameters](spec_parameters.md#parameters) - grammar, schema and examples for input and output parameters. @@ -14,5 +14,5 @@ If you want to learn how to write Packages and Applications using the specificat - [Packages](spec_packages.md#packages) - grammar, schema and examples for Packages. - [Actions](spec_actions.md#actions) - grammar, schema and examples for Actions. - [Triggers and Rules](spec_trigger_rule.md#triggers-and-rules) - grammar, schema and examples for Triggers and Rules. -- [Sequences](spec_sequences.md#sequences) - shema to compose multiple Actions into a sequence. +- [Sequences](spec_sequences.md#sequences) - schema to compose multiple Actions into a sequence. - [Normative & Non-normative References](spec_normative_refs.md) diff --git a/specification/html/spec_normative_refs.md b/specification/html/spec_normative_refs.md index 248fc4b..0e7bc5c 100644 --- a/specification/html/spec_normative_refs.md +++ b/specification/html/spec_normative_refs.md @@ -145,5 +145,20 @@ + + +--- + +
+ + + + + + +
Specification Index
+
diff --git a/specification/html/spec_packages.md b/specification/html/spec_packages.md index 6f3b5b1..920df97 100644 --- a/specification/html/spec_packages.md +++ b/specification/html/spec_packages.md @@ -166,3 +166,19 @@ my_whisk_package: - However, their information may be retrieved using respectively: - ```$ wsk trigger list -v``` - ```$ wsk api list -v``` + + +--- + +
+ + + + + + +
Specification Index
+
+ diff --git a/specification/html/spec_parameters.md b/specification/html/spec_parameters.md index 0537245..301a65e 100644 --- a/specification/html/spec_parameters.md +++ b/specification/html/spec_parameters.md @@ -242,3 +242,20 @@ In a Manifest or Deployment file, a parameter value may be set from the local ex - Processors or tooling that encounter ($) Dollar notation for values should attempt to locate the corresponding named variables set into the local execution environment (e.g., where the tool was invoked) and assign its value to the named input parameter for the OpenWhisk entity. - This specification does not currently consider using this notation for other than simple data types (i.e., we support this mechanism for values such as strings, integers, floats, etc.) at this time. + + + +--- + +
+ + + + + + +
Specification Index
+
+ diff --git a/specification/html/spec_sequences.md b/specification/html/spec_sequences.md index 0f6d3ca..d1e9482 100644 --- a/specification/html/spec_sequences.md +++ b/specification/html/spec_sequences.md @@ -57,3 +57,19 @@ sequences: newbot: actions: newbot-create, newbot-select-persona, newbot-greeting ``` + + +--- + +
+ + + + + + +
Specification Index
+
+ diff --git a/specification/html/spec_shared_entity_schema.md b/specification/html/spec_shared_entity_schema.md index f0a3a1c..3567c3a 100644 --- a/specification/html/spec_shared_entity_schema.md +++ b/specification/html/spec_shared_entity_schema.md @@ -88,3 +88,18 @@ annotations: > ### Notes - Several, non-normative Annotation keynames and allowed values for (principally for User Interface (UI) design) may be defined below for optional usage. + +--- + +
+ + + + + + +
Specification Index
+
+ diff --git a/specification/html/spec_trigger_rule.md b/specification/html/spec_trigger_rule.md index d37b801..5db0fb0 100644 --- a/specification/html/spec_trigger_rule.md +++ b/specification/html/spec_trigger_rule.md @@ -220,3 +220,19 @@ my_rule: trigger: my_trigger action: my_action ``` + + +--- + +
+ + + + + + +
Specification Index
+
+ diff --git a/specification/html/spec_types.md b/specification/html/spec_types.md index 3f621d8..dd2576e 100644 --- a/specification/html/spec_types.md +++ b/specification/html/spec_types.md @@ -389,3 +389,19 @@ inputs: type: object parameters: ``` + + +--- + +
+ + + + + + +
Specification Index
+
+ -- To stop receiving notification emails like this one, please contact ['"commits@openwhisk.apache.org" '].