Node.jsを利用してVisual Studio Team Serviceを触ってみる

# 前提
実行環境

| Platform |    Version   |
|:---------|:------------:|
| OS | Windows10　|
| Node　| v8.9.1　|

# 概要
Visual Studio Team Service(以下VSTS)に用意されている [REST API](https://www.visualstudio.com/en-us/docs/integrate/api/overview) を、Node.jsで色々と触った時のメモです。

# 準備
[vsts-node-api](https://github.com/Microsoft/vsts-node-api) というライブラリを利用しています。

[利用可能なAPIは中身を見てくれ！](https://github.com/Microsoft/vsts-node-api#apis) とのことですが、多分ほとんど(全部？)のAPIが使えるはずです。

## Personal Access Token(PAT)を用意する
APIを利用するには、URLの他にPATが必要です。

PATは以下の手順でVSTSのサイトより発行できます。

1. 右上の自アイコンにマウスオーバーしてメニューを表示させ、**Security** をクリックします。
![vsts_menu2.png](https://qiita-image-store.s3.amazonaws.com/0/125632/0e936f67-46b9-c7b6-e96a-3c61a04e6796.png)

1. PAT発行ページが表示されているはずですが、表示されていない場合はサイドバーの **Personal access tokens** をクリックしてください。
![vsts_menu3.png](https://qiita-image-store.s3.amazonaws.com/0/125632/c28ba17a-6dd5-bf48-7183-d1ba0799d730.png)

1. **Add** をクリックして必要な情報を選択、入力してPATを発行してください。

# 操作してみる
ソースコードはGitHubで公開しました。(当ブログのソースコードと出力タイミングを変えてあります)
(https://github.com/feb-acchan/operate-vsts)
お手柔らかにお願いします(笑)

## サイトへ接続する
```:commandline
URL=https://{your-account}.visualstudio.com/defaultcollection

PERSONAL_TOKEN=1234567890abcdefghijklmn
```

```js:sample.js
// your collection url
let collectionUrl = process.env.URL;

// ideally from config
let token = process.env.PERSONAL_TOKEN;

let authHandler = vsts.getPersonalAccessTokenHandler(token); 
return connect = new vsts.WebApi(collectionUrl, authHandler); 
```

URLとPATを WebApi へ渡す必要があるので、環境変数経由で渡して接続を確立させました。

## Project情報を取得してみる
接続ができたことを確認するために、とりあえず、Project情報を取得してみました。

なお、各種操作APIは直接定義・宣言するのではなく WebApi から get各種Api を呼び出したほうが楽です。

```js:sample.js
core = connect.getCoreApi();
projects = core.getProjects();
console.log('project', projects[0].name);
```

この画像のようにサイトには Maiden プロジェクトがあります。
![vsts_project.png](https://qiita-image-store.s3.amazonaws.com/0/125632/ed30ca45-3f78-d8cc-c85c-7d16cb29099e.png)

```:console
project Maiden
```

CoreApi.getProjects を利用して Maiden プロジェクトの取得が確認できたので、無事に接続できているようです。

## PullRequestの情報を取得してみる
APIに渡す際のJSON情報ですが、Interfaceを見ても私には全く理解できませんでした(笑)

上記 [REST API](https://www.visualstudio.com/en-us/docs/integrate/api/overview) と合わせて参照したほうが詳細が載っています。

今回は、前述のプロジェクトにあるPull Requestの情報を取得するため、REST APIページ **Get a list of pull requests in the project** へのRequestに該当する GitApi.getPullRequestsByProject を使いました。

抽出条件として必要なJSONデータは、[ここ]((https://www.visualstudio.com/en-us/docs/integrate/api/git/pull-requests/pull-requests#get-a-list-of-pull-requests-in-the-project)) を元に作成しました。

```js:sample.js
git = connect.getGitApi();
search_criteria = {"status": 1}
pullrequests = git.getPullRequestsByProject(project_name, search_criteria);
console.log('pullrequest', pullrequests[0].title);
```

REST APIの説明で status は enum{ Active, Abandoned, Completed } となっていますが、getPullRequestsByProject の引数 searchCriteria では GitInterfaces.GitPullRequestSearchCriteria型 となっています。ひも解くと PullRequestStatus なので `search_criteria = {"status": 1}` と active を示す 1 をセットしています。

理解が間違っていたらすみません。

ActiveなPullRequestが一つあります。
![vsts_pr.png](https://qiita-image-store.s3.amazonaws.com/0/125632/41abea71-c2aa-0679-3f9e-b814b741e044.png)

実行結果がこちらです。

```:console
pullrequest (Title)Pull Request 2回目
```

Pull Request のタイトルも正しいのでバッチリ取得できていますね。

## WorkItemを作成してみる
WorkItem が作れたら、ChatOpsよろしくと会話途中に突如降って湧いたアイデアをbot経由でWorkItemとして作成する等々利用用途が増えそうですね。

JSONは、[ここ](https://www.visualstudio.com/en-us/docs/integrate/api/wit/work-items#create-a-work-item)を参考に作成しました。

```js:sample.js
workitem = connect.getWorkItemTrackingApi();
json = [{"op": "add", "path": "/fields/System.Title", "value": "emergency"}]
result = workitem.createWorkItem(null, json, project_name, "Product Backlog Item");
console.log("id", result.id);
```

path に渡す値がわかりづらいのですが、他の Sample response などから簡単に導き出せたので、とりあえず普段作成する際に絶対必要となるWorkItemのタイトルだけ埋めることにしました。

どうしてもフィールド名がわからなかったら、getWorkItem で判明させるのも手ですね。

実行前のWorkItemがこちらです。
![vsts_pbis_bf.png](https://qiita-image-store.s3.amazonaws.com/0/125632/6c6c33c9-ba15-fbd3-41ae-bf387ff07db6.png)


そして、実行結果と実行後のWorkItemがこちらです。

```:console
id 9
```

![vsts_pbis_af.png](https://qiita-image-store.s3.amazonaws.com/0/125632/13f08267-59b6-f2e7-f9f9-16528d6e1fdc.png)

無事に console に表示された新しいIDの Product Backlog Item が作成されたことを確認できました。

# 最後に...
TypeScriptでコーディングしたほうがよかったかも？まずはTypeScriptデビューから始めようかな...