@atomist/automation-客户端

节点 模块 @atomist/automation-client 用于创建原子主义开发自动化。 开发自动化采取以下形式:

• Bot 命令 - 使用 命令处理器
• 对事件的反应 - 使用 事件处理器 自动 当事情发生时采取行动 就像有人评论一个问题, 发生
• Ingestors - 定义您自己的自定义事件,然后可以接受 行动

自动化客户端提供运行客户端的能力 连接到 Atomist API 以便它能够接收命令并按命令行事 事件.

见 原子论.com 财务报告和审定财务报表 docs.atomist.com (中文(中国大陆) ) 为了更多 详细信息.

概念

Atomist是一种服务和API,它能够实现开发自动化. 这个 原子学服务建立并维持一个重要事物的模型 给您的开发团队。 然后可以使用出箱自动化 或者用这个模型来建造自己的自动化设备.

更多信息请改为 概念。 。 。 .

开始

请安装 节点.js。验证正确的版本是 已安装, 请运行 :

$ node -v
v8.4.0
$ npm -v
5.4.1

使用 automation-client 模块

要开始在您的 Node.js 应用程序中使用此模块, 您必须在其中添加一个依赖性 package.json 运行以下命令:

$ npm install @atomist/automation-client --save

您可以在 https://atomist.github.io/automation-client-ts/ 页面存档备份,存于互联网档案馆 。 。 。 .

从样本开始

我们还提供一个工作项目,提供一些基本的自动化设备,可以用来快速启动. 存储器 处于 原子学家/自溶-种子。 。 。 .

要开始运行以下命令:

$ git clone [email protected]:atomist/automation-seed-ts.git
$ cd automation-seed-ts
$ npm install

见 自动种子 Ts 读取 为进一步 说明.

执行自动化

命令处理器

命令是可以通过Chat bot,卷曲或网络接口被引用的自动化.

要创建命令,请查看以下实例:

import { CommandHandler, Parameter} from "@atomist/automation-client/decorators";
import { HandleCommand, HandlerContext, HandlerResult } from "@atomist/automation-client/Handlers";

@CommandHandler("Sends a hello back to the client", "hello world")
//                                                   ^ -- defines the command to trigger
//                      "                                 this handler from the bot
export class HelloWorld implements HandleCommand {
//                                 ^ -- a command handler implements the HandleCommand
//                                      interface

    @Parameter({ pattern: /^.*$/, required: true })
//  ^            ^                ^ -- parameters can be marked required or optional
//  ^            ^ -- the parameter can be validated against a RegExp pattern
//  ^ -- this defines a user-provided parameter named 'name'
    public name: string;


    public handle(ctx: HandlerContext): Promise<HandlerResult> {
//  ^             ^ -- HandlerContext provides access to a 'MessageClient' for sending
//  ^                  messages to the bot as well as a 'GraphClient' to query your
//  ^                  data using GraphQL
//  ^ -- this method is the body of the handler and where the actual code goes
        return ctx.messageClient.respond(`Hello ${this.name}`)
//                               ^ -- Calling 'respond' on the 'MessageClient' will
//                                    send a message back to wherever that command
//                                    is invoked from (eg. a DM with @atomist in Slack)
            .then(() => {
                return Promise.resolve({ code: 0 });
//                                     ^ -- Command handlers are expected to return a
//                                          'Promise' of type 'HandlerResult' which
//                                          just defines a return code. Nonzero
//                                          return codes indicate errors.
            });
    }
}

上述宣布一个简单的机器人命令,可以通过 @atomist hello world。命令需要一个 调用参数 name。处理器将发出简单的问候信息.

详情请参见 命令处理器。 。 。 .

事件处理器

事件处理器是允许根据已注册的GraphQL订阅处理事件的自动化设备.

要创建事件处理器,请查看以下实例:

import { EventFired, EventHandler, HandleEvent, HandlerContext, HandlerResult }
    from "@atomist/automation-client/Handlers";

@EventHandler("Notify channel on new issue", `subscription HelloIssue {
    Issue {
      number
      title
      repo {
        channels {
          name
        }
      }
     }
}`)
//                                            ^ -- This is GraphQL subscription you want
//                                                 to match to trigger your handler.
//                                                 Queries can also be externalized.
export class HelloIssue implements HandleEvent<any> {
//                                 ^ -- an event handler implements the 'HandleEvent'
//                                      interface

    public handle(e: EventFired<any>, ctx: HandlerContext): Promise<HandlerResult> {
//                ^                   ^ -- 'HandlerContext' gives access to
//                ^                        'MessageClient' and 'GraphClient'
//                ^ -- 'EventFired' gives you access to the data that matched the
//                     subscription. Since GraphQL queries return JSON it is very easy
//                     to work with the data in JavaScript/TypeScript

        return Promise.all(e.data.Issue.map(i =>
            ctx.messageClient.addressChannels(`Got a new issue \`${i.number}# ${i.title}\``,
//                            ^ -- besides responding, you can address users and
//                                 channels in Slack by using the respective methods
//                                 on 'MessageClient'

                i.repo.channels.map(c => c.name))))
//              ^ -- in our correlated data model, repositories can be mapped to
//                   channels in a chat team. This will effectively send a message
//                   into each mapped channel
            .then(() => {
                return Promise.resolve({ code: 0 });
//                                     ^ -- Event handlers are expected to return a
//                                          'HandlerResult'. Nonzero code indicate
//                                          error occurred
            });
    }
}

此事件处理器注册 GraphQL 订阅 Issue 类型。 打开 Issue 处理器将发生的事件 向关联的懒人团队发送简单信息.

详情请参见 事件处理器。 。 。 .

登记处理器

为了在自动化客户端注册您的处理器, 请创建一个名为“ 自动化客户端” 的文件 atomist.config.ts 设置 内容如下:

import { Configuration } from "@atomist/automation-client/configuration";

import { HelloWorld } from "./commands/HelloWorld";
import { HelloIssue } from "./events/HelloIssue";

export const configuration: Configuration = {
//                          ^ -- 'Configuration' defines all configuration options

    name: "your_module_name",
//  ^ -- each automation-client should have a unique name

    version: "0.0.1",
//  ^ -- and a semver version

    teamIds: ["T29E48P34"],
//  ^ -- the ids of your chat teams which you can get by running '@atomist pwd'
//       leave empty to use your user defaults saved by atomist-config

    commands: [
//  ^ -- register all your command handlers
        () => new HelloWorld(),
    ],

    events: [
        () => new HelloIssue(),
    ],
//  ^ -- the same for event handlers

    token: process.env.GITHUB_TOKEN || "34563sdf......................wq455eze",
//  ^ -- configure a GitHub personal access token with read:org scope; this is used to
//       authenticate the automation-client with Atomist to make sure the client should
//       be granted access to the ingested data and chat team; leave null/undefined
//       to use your user default saved by atomist-config
};

此文件允许您注册您的处理器, 并为您的自动化客户指定名称和版本 .

运行自动化客户端

有几种方式可以运行您的自动化客户端,并让它连接到Atomist API.

本地运行

要在当地启动客户端 并让客户端听 即将到来的事件,只是运行:

$ atomist start

推向云铸

准备您的自动化客户端运行于任何 Cloud Foundry 请确保您有关于 云铸造厂和你有 云铸造厂CLI, 配置和登录 .

首先,你需要创建一个 manifest.yml 在您的节点根中 项目。 将以下最小内容放入文件 :

applications:
- name: YOUR_APP_NAME
  command: $(npm bin)/atomist-client
  memory: 128M
  buildpack: https://github.com/cloudfoundry/nodejs-buildpack
  env:
    GITHUB_TOKEN: <your GITHUB_TOKEN>
    SUPPRESS_NO_CONFIG_WARNING: true

有其他推荐的方法 让你的 GITHUB_TOKEN 输入您的自动化客户实例 . 看看这个 cfenv 比如说

下一个请添加 "engines" 顶级条目 package.json 类似如下:

  "engines": {
    "node": "8.x.x",
    "npm": "5.x.x"
  }

现在你准备好 cf push 您的自动化服务器到 Cloud Foundry :

$ cf push

REST APIs 软件

当开始的时候 automation-client 暴露出一些可以通过HTTP访问的端点.

认证

端点由HTTP Basic Auth或以符号为基础的认证保护. 启动客户端时,你会看到 下列格式的日志消息:

2017-09-20T08:22:32.789Z - info	: Auto-generated credentials for web endpoints are user 'admin' and password '4d6390d1-de5c-6764-a078-7308503ddba5'

默认情况下,自动化客户端自动生成一些您使用的证书 。 要配置您的证书, 请更改 atomist.config.ts 并将以下一节列入:

export const configuration: Configuration = {
    ...
    http: {
        enabled: true,
        auth: {
            basic: {
                enabled: true,
                username: "some user",
                password: "some password",
            },
        },
    },
};

终点

获取管理端点

举例来说,这里有一个命令来获取当前衡量标准:

$ curl -X GET \
     http://localhost:2866/metrics \
     -H 'authorization: Bearer 34563sdf......................wq455eze"' \
     -H 'content-type: application/json'

上述端点均为HTTP GET并每次默认获取无记名和基本认证. 详情见下文: 认证.

引用命令处理器

可通过具有下列有效载荷的HTTP POST来援引指令处理器:

$ curl -X POST \
    http://localhost:2866/command \
    -H 'content-type: application/json' \
    -H 'authorization: Bearer 34563sdf......................wq455eze"'
    -d '{
          "parameters": [{
            "name": "name",
            "value": "cd"
          }],
          "mapped_parameters": [{
            "name": "sender",
            "value": "kipz"
          },{
            "name": "userName",
            "value": "cd"
          }],
          "secrets": [{
            "uri": "github://user_token?scopes=repo",
            "value":"4...d"
          }],
          "command": "HelloWorld",
          "correlation_id": "6cb72bf7-77b4-4939-b892-00000701fa53",
          "team": {
            "id": "T1L0VDKJP",
            "name": "Atomist QA"
          },
          "api_version": "1"
        }'

支助

一般性支持问题应在缔约方会议 #support 我们社区Slack团队的频道 时间 原子主义-社区. slack.com。 。 。 .

如果你发现问题,请创建 问题。 。 。 .

发展

您需要安装 节点 建造和测试这个项目.

要运行测试, 请将 GITHUB TOKEN 定义为任何可重传访问的有效符号 。 测试 将创建和删除仓库.

定义 GITHUB VISibility = public,如果您想要这些是公开的;默认是私有的. 如果你不支付私人的回购,就会得到422的回放.

构建和测试

释放

为了创造项目的新发布,我们按下原子主义生命周期消息的按钮 在 #自定义客户端- ts 频道 在原子主义社区Slack.

创建于 原子学家。 。 。 . 需要帮忙吗? 加入我们的黑队。 。 。 .