BSAM CLI是一个基于BCE SAM规范的命令行工具，它提供了本地开发环境，帮助您在把函数上传到百度智能云CFC之前，在本地进行函数的开发、分析和执行。

工具安装

1.安装Python3.6及以上

2.安装Docker

BSAM CLI依赖Docker，所以您需要提前安装并运行Docker服务，关于各个操作系统Docker的安装可以参考Docker官网。

为了查看Docker服务是否已运行，您可在安装完成后执行docker ps等命令进行验证。

3. 安装 BSAM CLI

执行 pip3 install bce-sam-cli 即可完成安装。

安装完成后，执行bsam命令，出现下面的提示说明安装成功。

Usage: bsam [OPTIONS] COMMAND [ARGS]...

  BCE Serverless Application Model (SAM) CLI

  The BCE Serverless Application Model provide a simplified way of defining
  the CFC functions, triggers and other services needed by your serverless
  application.You can find more in-depth guide about the SAM specification
  here: https://github.com/bcelabs/serverless-application-model.
  
  ... ...
  

功能概述

• init 初始化一个serverless应用，应用文件夹包含源码以及template文件
• config 配置连接远端CFC的相关参数
• package 打包本地源码
• deploy 将本地serverless应用部署到CFC
• local 本地运行以及测试serverless应用

1.初始化

主要参数：

• -l / --location 生成项目时template的所在路径，可以为git、http、zip以及文件夹
• -r / --runtime 选择可支持的运行时环境
• -o / --output-dir 项目生成的文件夹路径
• -n / --name 项目名称（也是之后云函数的名称）

通过init命令初始化一个工作目录，指定runtime为nodejs10。

$ bsam init --runtime nodejs10 --name bsam-app

该命令会在当前目录下生成一个bsam-app文件夹，目录结构如下：

$ cd bsam-app
$ tree
.
├── README.md
├── src
│   ├── app.js
│   ├── package.json
│   └── tests
│       └── unit
│           └── test_handler.js
└── template.yaml

app.js是函数代码文件。

template.yaml是BCE SAM模型文件，定义了函数的函数名、runtime、handler等元信息。BSAM CLI从模型文件中获取函数配置，从而对正确地执行函数。

2.创建配置文件

主要参数：

• -l / --location 配置信息所在路径，默认为~/.bce
• --ak 以及 --sk
• --region

函数部署功能需要您在home目录下预先创建好bce config和credentials文件，将access key、secret key和region信息写入其中。

执行bsam config命令可帮助您快速创建这两个文件。

3.函数打包与部署

在本地开发和测试完函数后，进入函数项目根目录，可以使用bsam package和bsam deploy命令部署到CFC。

package命令将压缩您的代码文件，生成一个.zip文件。

deploy命令会将.zip文件上传到CFC，若该函数不存在则创建一个新的函数，若您在模型文件中定义了触发器，那么触发器也会被一并创建。若该函数已存在，则会更新该函数的代码和配置。

deploy支持指定部署到华北-北京、华东-苏州或华南-广州机房。

4.生成事件

为了使您更方便的开发测试CFC函数，您可以创建并自定义触发源事件。

bsam local generate-event <service> <event> [options]

目前支持的service有bos、dueros、http。每种服务的事件类型不同，以dueros为例，它支持四种event：

5.安装依赖/编译

在执行函数之前，需要做一些额外工作来扫清障碍。若您的函数依赖第三方库，BSAM CLI可帮您自动安装这些依赖。

bsam local install

该命令会在当前目录查找和读取BCE SAM模型文件template.yaml，若模型文件不在当前目录，您可使用-t参数指定文件的路径。

您可使用CodeUri字段指定函数所在目录，BSAM CLI会读取该目录中的package.json（Node.js函数）或requirements.txt（Python函数），根据其中的配置下载所需的模块。 您也可以手动在该目录中放置依赖文件。

Java

Java是编译型语言，在执行前需要编译函数(与其类似的有golang)。执行install命令时，BSAM CLI使用maven下载依赖、编译函数，后者会读取本地的pom.xml文件。 若您的Java函数依赖本地jar包，可将jar包放在bsam-app目录下，在pom.xml文件中指定jar包的位置，示例如下：

<dependency>  
	<groupId>org.ibm</groupId>  
	<artifactId>jms</artifactId>  
	<version>1.0.0</version>
	<scope>system</scope>
	<systemPath>${project.basedir}/lib/user-local.jar</systemPath>
</dependency>

本地jar包只能放在bsam-app目录范围内，放到其它位置不会被挂载到容器中，无法被maven找到。

install命令执行完毕后，bsam-app下会新建一个target目录，其中的 xx-xx-jar-with-dependencies.jar为编译好的包含依赖的jar包。

python

install命令执行完毕后，源码路径src下会新建一个site-packages目录，所有依赖都放置在该文件夹下，其项目路径结构如下：

.
├── README.md
├── src                         
│   ├── __init__.py
│   ├── site-packages           <-- 存放依赖文件
│        ├── lib1
│        ├── lib2
│   ├── ...
│   ├── index.py                <-- python 函数源码
│   └── requirements.txt        <-- Python 依赖管理文件
├── template.yaml               <-- BSAM 模型文件
└── tests                       <-- 单元测试
    └── unit
        ├── __init__.py
        └── test_handler.py

注意：

• 当执行函数代码打包命令 bsam package时，bsam会将site-packages下的依赖抽取出来和用户编写的业务代码一起打包
• 这种依赖与源码分离的项目结构，只能利用bsam命令进行调试与本地运行，如果用户需要利用本地编译器进行运行，可以为其配置环境变量$PYTHONPATH,参考代码如下

    export PYTHONPATH = .../src/sitepackages:$PYTHONPATH

6.执行函数

在执行函数时，需要传递函数的Logical ID和event json文件，bsam local invoke也接受stdin作为event输入。

每次执行函数前，BSAM CLI会自动检查是否有可更新的镜像，您可通过--skip-pull-image参数取消检查。

示例：

# invoke时传入event json文件
$ bsam local invoke bsam-app -e event.json

# 使用stdin传入event
$ echo '{"msg":"hello, cfc"}' | bsam local invoke bsam-app

# 查看更多选项
$ bsam local invoke --help

该命令会在当前目录查找和读取BCE SAM模型文件template.yaml，若模型文件不在当前目录，您可使用-t参数指定文件的路径。

若您执行Java函数，请用CodeUri字段指定上一步中编译好的jar包文件路径。

7.函数调试

bsam local invoke 命令支持调试功能，您可借助本地IDE完成调试，下面以VS Code为例介绍如何调试。

调试Node.js函数

1. 用VS Code打开工作目录bsam-app。
2. 执行命令bsam local invoke -e event.json --debug-port 5858 bsam-app，这里指定容器暴露的调试端口为5858。

3. 在VS Code的菜单栏中，选择"Debug" ，"Open Configurations"，在打开的launch.json中编辑内容如下：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "BSAM CLI Node.js Debug",
               "type": "node",
               "request": "attach",
               "address": "localhost",
               "port": 5858,
               "localRoot": "${workspaceRoot}/bsam-app/src",
               "remoteRoot": "/var/task",
               "protocol": "inspector",
               "stopOnEntry": false,
           }
       ]
   }

   其中，"port"字段值要和第二步中指定的端口保持一致，"localRoot"是代码文件所在的目录。 "protocol"表示Node.js使用的调试协议，请指定为"inspector"。 "localRoot" 表示函数源码所在的本地路径，其中${workspaceRoot}是VSCode的一个环境变量，表示您当前的工作空间路径，<FUNCTION_PATH> 是函数在当前工作空间的相对路径。 关于每个字段的详细解释和VS Code Debugger的更多用法，您可参考Node.js debugging in VS Code

4. 在您的代码中打上断点，然后选择"Debug"，"Start Debugging" ，开始调试。

调试Python函数

1. 用VS Code打开工作目录bsam-app。
2. 执行命令bsam local invoke -e event.json --debug-port 5890 bsam-app，这里指定容器暴露的调试端口为5890。

3. 在VS Code的菜单栏中，选择"Debug" ，"Open Configurations"，在打开的launch.json中编辑内容如下：

   {
       "version": "0.2.0",
       "configurations": [    
           {
              "name": "BSAM CLI Python Debug",
              "type": "python",
              "request": "attach",
              "port": 5890,
              "host": "localhost",
              "pathMappings": [
                  {
                      "localRoot": "${workspaceFolder}/bsam-app/src",
                      "remoteRoot": "/var/task"
                  }
              ]
           }
       ]
    }

   其中，"port"字段值要和第二步中指定的端口保持一致，"localRoot"是代码文件所在的目录。 关于每个字段的详细解释和VS Code Debugger的更多用法，您可参考Python debugging in VS Code

4. 在代码中添加断点，在VS Code菜单栏中选择"Debug"，"Start Debugging"，程序会自动停在代码中的断点，开始调试。

调试Java函数

1. 用VS Code打开工作目录bsam-app。
2. 执行命令bsam local invoke -e event.json --debug-port 8890 bsam-app，这里指定容器暴露的调试端口为8890。

3. 在VS Code的菜单栏中，选择"Debug" ，"Open Configurations"，在打开的launch.json中编辑内容如下：

   {
       "version": "0.2.0",
       "configurations": [
           {
               "type": "java",
               "name": "Debug Java (Attach)",
               "request": "attach",
               "hostName": "localhost",
               "port": 8890
           }
       ]
   }

   其中，"port"字段值要和第二步中指定的端口保持一致。
   关于每个字段的详细解释和VS Code Debugger的更多用法，您可参考Debugging Java in VS Code

4. 在您的代码中打上断点，然后选择"Debug"，"Start Debugging" ，开始调试。