連載第4回目の目的
連載第4回目と第5回目では、Excel VBAによるGitHubリポジトリの操作について取り上げます。GitHubは、ソフトウェア開発のためのツールとして、ソフトウェアエンジニアにとって定番とも言える存在です。しかし非エンジニアがGitHubの機能に注目して、ビジネス用途でGitHubを活用するという動きが近年は見られるようになりました。そこで今回と次回は、GitHubのリポジトリをプロジェクト管理用に作成し、その状況を確認できるExcelワークシートを作成する例を紹介します(図1)。まず今回は、GitHubの概要について紹介し、リポジトリの作成や必要な設定、そしてAPIを使えるようになるまでを取り上げます。
▼完成サンプルのソースコード
https://github.com/wateryinhare62/mynavi_excelvba_webservice
なお、本連載では動作確認をWindows 10 Pro(64bit)、Microsoft 365(Excel 16.0、VBA 7.1)で行っています。旧バージョンや単体のExcelで試す場合にはご注意下さい。
GitHubについて
GitHubは、ソフトウェア開発支援プラットフォームのひとつです。主にソースコードの保管と管理に用いられており、バージョン管理システムにはGitというオープンソースソフトウェアが用いられています。Microsoft社の傘下のGitHub社によって運営されています。基本的に無償で使用できますが、TeamとEnterpriseという有償プランもあります。今回扱っているのは、無償プランで使用できる機能のみです。
▼GitHub
https://github.com/
GitHubによるソースファイルの管理とは?
GitHubでは、ソースファイルをリポジトリという単位で取り扱います。リポジトリ=ソフトウェアの保管庫、と思えばよいでしょう。リポジトリに登録したソースファイルは公開されて他の開発者と共有できるほか、履歴を残しながら更新することもできます。リポジトリには、公開されていて誰でも利用できるpublicなものと、基本的に所有者のみが使用するprivateなものがあります。
最近は、多くのオープンソースソフトウェアが、自前のホスティングスペースを持たずに、GitHubにホストすることが増えています。いったんリリースしたソフトウェアを改変しながら公開できるので、開発者のとっての使い勝手が優れているのです。今後も、ソフトウェアを探していたらGitHub上のリポジトリにたどり着いた、ということが増えてくるでしょう。
今回の内容とは直接の関係がないので詳細は省きますが、GitHubではフォークというコピーを作って独自に改変したり、それをおおもとのソースコードにマージしたり、マージをリクエストするプルリクエストなどの機能を備えています。
リポジトリとプロジェクト管理
GitHubは、ソフトウェアの保管庫という位置付けとは別に、プロジェクト管理のツールという一面も持っています。そのものズバリのProjectという機能があり、本記事の掲載時点ではベータ版ですが、Excelワークシートのような見た目の表を用いてチームによる開発をサポートします。
そこまで大ごとにしなくても、GitHubにはIssues、Milestonesという機能があり、それぞれ解決すべき問題(issue)の管理、中間目標(milestone)の管理などを行うことができます。これらはもちろん、ソースコードの管理のためにバグや要望の提出、クリアすべき期限の設定に用いるのですが、シンプルにビジネスにおける課題管理などにも利用できます。
例えば、読者がソフトウェア開発会社の営業部門のスタッフだったとして、自らもGitHubを使いこなしてその機能に通じているとしたら、開発部門のスタッフとの意思疎通や連携作業もスムースに進むことが期待できます。これはもちろん、現実のプロジェクトにおいてGitHubを使っていくということでも構わないのですが、自分でもGitHubのリポジトリを作ってIssuesやMilestonesを使いこなすことで、GitHub利用の敷居を下げておけば大きなアドバンテージになり得ます。
作成するサンプル
今回と次回で作成していくサンプルは、各自が自由に入力するissueを、締め切り(milestone)までの日数に応じて色分けして表示するというものです。GutHubにサインインしなくても、Excelワークシートを開いてデータの取得を行えば、どのissueに締め切りが迫っているのかをすぐに把握できます。なお、色分けは以下のようになります。
- 白:締め切りの設定がないか1か月以上の猶予あり
- 黄:締め切りまで30日以内
- 赤:締め切りまで7日以内
- 灰:締め切り超過
クローズ(解決したなどでissue自体が無効になった)したissueは薄字で表示するようにします。
GitHubリポジトリの準備
今回は、読者がそれぞれ独自にprivateなリポジトリを作成し、そこにissueやmilesstoneを設定し、それらを表として確認できるサンプルを作っていきます。そこで、まずはリポジトリを準備しましょう。これには、GitHubアカウントが必要ですので、持っていないという読者はまずGitHubアカウントを作成して下さい。GitHubアカウントは、メールアドレスがあれば作成できます。
▼Join GitHub
https://github.com/signup
リポジトリを作成する
GitHubにサインインします。すでにGitHubを使っている場合には、左ペインに自分のリポジトリ、メンバーになっているリポジトリが一覧で表示されますが、アカウントの作成直後には何もないはずです。ここで、緑色の[New]ボタンをクリックして、リポジトリの作成をはじめます(図2)。
「Create a new repository」画面でリポジトリの作成を行います(図3)。
入力すべき項目は表1のとおりです。
▲表1:リポジトリ作成時に設定する項目
項目 | 内容 |
---|---|
Owner | リポジトリの所有者で、通常はアカウントの所有者本人。 |
Repository name | 作成するリポジトリの名前。これは、所有者ごとにユニークである必要がある。はじめてリポジトリを作るなら、使用可能な文字種にさえ注意すればどのような名前でも良い。ここでは、「mynavi-ew-github」としておく。もし変更する場合には、Excelワークシート中のリポジトリ名も合わせて変更する。 |
Description | リポジトリの説明。「マイナビ連載「Excel VBAでWebサービス」のためのリポジトリです。」としておく。 |
Public, Private | リポジトリを公開する場合はPublic。今回はPrivateにしておく。Privateにすることで、外部に公開されず自分用となる。 |
Initialize this repository with: | 「Add a README file」にのみチェックを入れる。 |
これらを入力、設定したら[Create repository]ボタンをクリックします。画面が変化し、リポジトリが作成されていることを確認できます。ここで、画面上に所有者名とリポジトリ名が表示されていて、その脇に「Private」と表示されていることを確認して下さい(図4)。
Milestonesを入力する
続けて、issueを入力していきますが、issueにはmilestoneを設定することが多いので、先にmilestoneを入力しておきます。milestoneの作成はIssuesの機能内で行いますので、まずはリポジトリのトップ画面上部のナビゲーションから[Issues]をクリックしてIssuesの一覧画面としておきます。リポジトリの作成直後なので、何も作成されていないはずです(図5)。
milestoneは、ここで[Milestones]をクリックすることで作成できます。Milestoneは1個もないはずなので一覧は空です。ここで、milestoneを4個作っていきます。右上の[New milestone]あるいは中央の「Create a Milestone」をクリックします(図6)。
「New milestone」画面では、タイトル(Title)、締め切り日(Due date)、Description(説明)を入力して、[Create milestone]をクリックします。締め切り日は必ず設定しましょう。色分けを試すために記事を読んでいる日に合わせて適宜設定して下さい。タイトルと説明は、それらしいものであれば何でもかまいません(図7)。
表2:Milestonesの設定内容
番号 | 位置付け | タイトル | 締め切り日 |
---|---|---|---|
1 | 期限超過 | 企画書提出 | 先月末日 |
2 | あと7日 | プロジェクトスタート | 今日+7日 |
3 | あと30日 | 中間報告 | 今日+30日 |
4 | 31日以上 | プロジェクト完成 | 今日+31日以降 |
milestoneが作成できると、図8のようになります。これを4個、繰り返して下さい。
issueを入力する
milestoneを作成したら、issueの一覧に戻ります。そこで改めて[New issue]をクリックしてissueの作成を開始します。issueには、issueの担当者を明確にする「Assignee」、issueの種類を示す「Labels」、関連付けるプロジェクトを示す「Projects」、issueの締め切りを示す「Milestone」などを設定できます。
ここではissueのタイトルと内容、そしてmilestoneを右の歯車アイコンから選択します。[Submit new issue]をクリックすれば、issueの作成が完了です(図9)。issueはいくつあってもよいので、上記のmilestoneを振り分けながら、複数作成して下さい。
ここまでで、サンプルの実行に必要なissueとmilestoneの登録が終了しました。
GitHub APIを使う準備
GitHubは、このようにリポジトリの管理、解決すべき問題の管理など、さまざまな機能を備えています。これらは、基本的にGitHubのWebサイトで作業しますが、外部から利用可能なAPIが公開されています。
GitHub API
これはGitHub APIと呼ばれています。GitHub APIの主な機能は以下のとおりです。今回使うのは、一番上のIssues(課題)の生成・更新・取得・削除に関連するAPIです。
- Issues(問題)の生成・更新・取得・削除
- Repository(リポジトリ)の生成・更新・取得・削除
- Organizations(組織)の一覧やメンバーの取得
- Notifications(通知)やFeeds(フィード)の取得
- Gist(ソースコードの断片)の生成・更新・取得・削除
- Pull Request(プルリクエスト)の生成・更新・取得・削除
2022年1月現在、GitHub APIにはREST API(v3)とGraphQL API(v4)の2種類があります。REST APIはその名のとおりRESTfulなAPIであり、他のREST APIを使ったことのある人であれば、使い始めるのが容易です。これに対して最新のGraphQL APIでは、APIのエンドポイントが統一され、複数のリクエストを1回にまとめることができたり、必要な要素のみを取得できたりするなどの便利さがあります。一方でエラーハンドリングが難しいといったこともあり、初学者には負担が大きくなるということも考えられます。REST APIとGraphQL APIではどちらを使っても同じことを実現できますが、古くからあるREST APIのほうがシンプルで入門向きですので、今回はREST APIを用いていきます。
個人アクセストークンの取得
GitHub APIを使うには、個人アクセストークン(PAT)による認証が必要です。2021年8月まではGitHubのアカウントとパスワードでAPIを使えましたが、現在は個人アクセストークンによる認証に切り替わっています。トークンと言っても特に難しく考えることはなく、API利用時にはパスワードの替わりに個人アクセストークンを使うという認識でよいでしょう。まずは、この個人アクセストークンを取得するところからはじめましょう。
GitHub APIは,publicなリポジトリの操作は認証なしで行えますが、リクエスト数は1時間あたり60件までに制限されています。認証されている場合はリクエスト数は1時間あたり5,000件までと大幅に緩和されますから、基本的には個人アクセストークンによる認証込みでAPIを使うことをお勧めします。
今回の例のように、privateなリポジトリの操作には認証が必須となります。ですので、個人アクセストークンの取得を行う手順を押さえておきましょう。
個人アクセストークンの取得は、以下のように行います。まず、GitHubのサイトにサインインします。
サインイン直後の画面右隅にあるプロフィールアイコンをクリックし、表示されるメニューから[Settings]をクリックします(図10)。
画面が切り替わりますので、左側にずらっと表示される項目の下の方にある[Developer settings]をクリックします(図11)。
さらに画面が切り替わりますので、まずは左側に表示される項目にある[Personal access tokens]をクリックします。そして、画面右上にある[Generate new token]をクリックしてトークンを作成していきます(図12)。このとき、パスワードを求められることがありますから、そのときはGitHubアカウントのパスワードを入力します。
「New personal access token」画面では、「Note」欄に作成したいトークンの説明、「Expiration」にはトークンを有効にする日数、「Select scopes」でトークンに付与するスコープ(権限)を設定します。今回は、privateなリポジトリへのアクセスを行いますので、「repo」を選択しておきます。 ひととおり項目を設定したら、画面下部にある[Generate token]をクリックします。これで、トークンが作成されます(図13)。
作成したトークンの情報が表示されます(図14)。「Make sure to copy your personal access token now. You won’t be able to see it again!」(今すぐ個人アクセストークンをコピーしてください。 二度と見ることはできません!)と表示されているように、トークンはここで「必ず」控えておきましょう。この下にある薄い緑色の背景の項目がトークンです。コピーアイコンをクリックして、メモ帳などのテキストエディタに貼り付けて、ファイルとして保存しておきましょう。なお、[Delete]をクリックするとトークンを削除できますから、セキュリティ上、不要になったトークンはできるだけ削除するようにしましょう。
API呼び出しの確認
個人アクセストークンを取得できたら、手動でAPI呼び出しを行ってみましょう。これは、Windows PowerShell上で行います。Unix系OSのcurlコマンドに相当する、PowerShellのInvoke-WebRequestコマンドレットを使って、API呼び出しを行います。
[NOTE]PowerShell 7.xが必要
この操作は、PowerShell 7以上が必要です。Windows 10に標準でインストールされているのはPowerShell 5.1ですので、下記からPowerShell 7.2(本記事執筆時点の最新バージョン)を入手してインストールして下さい。PowerShell 7.2はPowerShell 5.1とは別のアプリケーションとしてインストールされますので、両方を使い分けることが可能です。
▼Windows への PowerShell のインストール
https://docs.microsoft.com/ja-jp/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2
PowerShell 7.2は、[スタート]-[PowwerShell]-[PowerShell 7(x64)]を選択して実行できます。まずは、以下のようにコマンドを実行してみましょう(プロンプトは、カレントフォルダの表示を省いています)。
PS> invoke-webrequest ←コマンドを入力
Supply values for the following parameters:
Uri: https://api.github.com/zen ←APIのURLを指定
StatusCode : 200
StatusDescription : OK
Content : Mind your words, they are important.
…略…
コマンドに引数を指定しなかったので、必要な引数であるUriを指定せよと促してきます。ここでは、「https://api.github.com/zen」を指定しました。このAPIは、GitHub API(REST API)の「GitHubの設計思想」をランダムで取得するものです。このように、GitHub APIのURLは「https://api.github.com/~」となります。このAPIのパスは/zenで、一切の引数はありません。結果として、リクエストのステータス(200 OK)と内容(Mind your words, they are important.)が返ってきます。
略されている部分には、レスポンスヘッダの情報も表示されています。しかし、そのままでは簡略化されている(値などは表示されない)ので、以下のようにしてレスポンスヘッダの内容を表示させてみましょう。今度は、引数に直接URLを指定し、コマンドレットの出力を$result変数にセット、そして$resultのHeadersプロパティのみを表示させてみました。
PS> $result=(invoke-webrequest https://api.github.com/zen) ←コマンドを入力
PS> $result.Headers ←Headersプロパティを表示
Key Value
--- -----
…略…
X-RateLimit-Limit {60} リクエストの上限
X-RateLimit-Remaining {59} 残っているリクエスト数
X-RateLimit-Reset {1642682131} リセットまでの時間(秒)
X-RateLimit-Resource {core}
X-RateLimit-Used {1} 使用済みのリクエスト数
…略…
ここまでのリクエストでは、トークンを使用した認証は行っていませんから、リクエストの上限は60となっています。しかし、リクエスト自体はうまくいっています。今度は、トークンによる認証を-Authenticationパラメータと-Credentialパラメータを加えて行ってみます。
PS> $user="account" ←GitHubのアカウントを指定
PS> $pass="token" ←取得したトークンを指定
PS> $secret=ConvertTo-SecureString $pass -AsPlainText -Force ←トークンを暗号化
PS> $credential=New-Object System.Management.Automation.PSCredential($user, $secret) ←資格を作成
PS> $result=(Invoke-WebRequest https://api.github.com/zen -Authentication Basic -Credential $credential)
PS> $result.Headers
…略…
X-GitHub-Media-Type {github.v3; format=json}
X-RateLimit-Limit {5000}
X-RateLimit-Remaining {4998}
X-RateLimit-Reset {1643111330}
X-RateLimit-Used {2}
…略…
改めてX-RateLimit-LimitとX-RateLimit-Remainingを見ると、それぞれ5000と4999になっていますから、トークンによる認証がうまくいっていることがわかります。なお、ここではHeadersプロパティを中心に見ましたが、コンテンツそのものを見るにはContentプロパティを用います。
まとめ
今回は、GitHub APIを使ってIssuesを一覧表示するサンプル作成の下準備として、GitHubの概要、GitHub APIの概要とWebサービスの呼び出しの手順を紹介しました。これらはExcel VBAに限った話ではなく、GitHub APIを扱う場合に応用できるのではないかと思います。次回は、実際にGitHubを使うためのExcelワークシートを作っていきます。
WINGSプロジェクト 山内直著/山田祥寛監修
<WINGSプロジェクトについて>テクニカル執筆プロジェクト(代表山田祥寛)。海外記事の翻訳から、主にWeb開発分野の書籍・雑誌/Web記事の執筆、講演等を幅広く手がける。一緒に執筆をできる有志を募集中