前提
実行環境
| Platform | Version |
|---|---|
| OS | Windows10 |
| Node | v8.9.1 |
概要
Visual Studio Team Service(以下VSTS)に用意されている REST API を、Node.jsで色々と触った時のメモです。
準備
vsts-node-api というライブラリを利用しています。
利用可能なAPIは中身を見てくれ！ とのことですが、多分ほとんど(全部？)のAPIが使えるはずです。
Personal Access Token(PAT)を用意する
APIを利用するには、URLの他にPATが必要です。
PATは以下の手順でVSTSのサイトより発行できます。
-
右上の自アイコンにマウスオーバーしてメニューを表示させ、Security をクリックします。
-
PAT発行ページが表示されているはずですが、表示されていない場合はサイドバーの Personal access tokens をクリックしてください。
-
Add をクリックして必要な情報を選択、入力してPATを発行してください。
操作してみる
ソースコードはGitHubで公開しました。(当ブログのソースコードと出力タイミングを変えてあります)
(https://github.com/feb-acchan/operate-vsts)
お手柔らかにお願いします(笑)
サイトへ接続する
URL=https://{your-account}.visualstudio.com/defaultcollection
PERSONAL_TOKEN=1234567890abcdefghijklmn
// 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 を呼び出したほうが楽です。
core = connect.getCoreApi();
projects = core.getProjects();
console.log('project', projects[0].name);
この画像のようにサイトには Maiden プロジェクトがあります。
project Maiden
CoreApi.getProjects を利用して Maiden プロジェクトの取得が確認できたので、無事に接続できているようです。
PullRequestの情報を取得してみる
APIに渡す際のJSON情報ですが、Interfaceを見ても私には全く理解できませんでした(笑)
上記 REST API と合わせて参照したほうが詳細が載っています。
今回は、前述のプロジェクトにあるPull Requestの情報を取得するため、REST APIページ Get a list of pull requests in the project へのRequestに該当する GitApi.getPullRequestsByProject を使いました。
抽出条件として必要なJSONデータは、ここ を元に作成しました。
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が一つあります。
実行結果がこちらです。
pullrequest (Title)Pull Request 2回目
Pull Request のタイトルも正しいのでバッチリ取得できていますね。
WorkItemを作成してみる
WorkItem が作れたら、ChatOpsよろしくと会話途中に突如降って湧いたアイデアをbot経由でWorkItemとして作成する等々利用用途が増えそうですね。
JSONは、ここを参考に作成しました。
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がこちらです。
そして、実行結果と実行後のWorkItemがこちらです。
id 9
無事に console に表示された新しいIDの Product Backlog Item が作成されたことを確認できました。
最後に...
TypeScriptでコーディングしたほうがよかったかも？まずはTypeScriptデビューから始めようかな...