1. Microsoft Graph API Library for Go
2019-10-28 Takeshi Yaegashi
Go Conference 2019 Autumn

2. 自己紹介
八重樫 剛史 Takeshi Yaegashi
● 株式会社バンダイナムコスタジオ所属
● Linux・Unix・OSS・低レベルなことが好きなエンジニア
● ホームページ・ブログ https://l0w.dev
● Go のお仕事
○ Raspberry Pi を使った IoT 案件
○ スマホゲームアプリのサーバ
● Go のお話
○ golang.tokyo #25「golang binary hacks」
○ golang.tokyo #26「Raspberry Pi + Go で IoT した話」

3. 本日のお話
msgraph.go
● https://github.com/yaegashi/msgraph.go
● Microsoft Graph の紹介
● msgraph.go の使用方法とアプリケーション、デモ (動画)
● Go 言語用クライアントライブラリの状況
● msgraph.go の実装と工夫した点
● 今後の計画

4. Microsoft Graph の紹介

5. Microsoft Graph API とは
● Microsoft のクラウドサービス (Office 365 など) を扱う統合 API
https://docs.microsoft.com/ja-jp/graph/overview
● 次のようなリソースを操作するアプリを作成できる
○ ユーザー・グループ・デバイス・ライセンス (Azure Active Directory)
○ メール・連絡先・予定表・チャット (Outlook, Teams)
○ ストレージ・ファイル・サイト (OneDrive, SharePoint)
● Office 365 を導入している会社や個人にとって利用価値が高い API

6. Microsoft Graph API プログラミング
● 共通のエンドポイントを使用する REST API セット
○ API Endpoint (v1.0): https://graph.microsoft.com/v1.0
○ API Reference: https://docs.microsoft.com/ja-jp/graph/api/overview
● 各言語・処理系用のクライアントライブラリ (SDK)
https://microsoftgraph.github.io/msgraph-sdk-design/
○ .NET(C#), Java, JavaScript, Objective C, PHP, Ruby, Python, …
○ 2019年10月現在、公式のGo言語用ライブラリはまだない

7. Go 言語用のクライアントライブラリの状況
● GitHub をリポジトリ検索してみると…
○ https://github.com/search?l=Go&q=msgraph&type=Repositories
○ go-msgraph, msgraph-go, msgoraph, … 未完のプロジェクトが多数
● msgraph.go = 今回紹介するライブラリ
○ https://github.com/yaegashi/msgraph.go
○ 2019年7月に開発開始
○ msgraph.go という名前は既存のライブラリとの衝突を避けた結果

8. msgraph.go 使用法とアプリの例

9. msgraph.go 使用法：Graph Client の作成
import "github.com/yaegashi/msgraph.go/auth"
import msgraph "github.com/yaegashi/msgraph.go/v1.0"
// Create HTTP client with Azure AD OAuth2 device authorization grant
m := auth.NewTokenManager()
t, err := m.DeviceAuthorizationGrant(tenantID, clientID, scope, nil)
if err != nil { /*...*/ }
httpClient := t.Client(context.Background())
// Create MS Graph client
graphClient := msgraph.NewClient(httpClient)
● 最初に Graph Client を作成する
● Azure Active Directory に対して OAuth2 認証を行う http.Client が必要
https://github.com/yaegashi/msgraph.go/tree/master/auth

10. msgraph.go 使用法：REST API 発行
// Get current user’s information
// "GET https://graph.microsoft.com/v1.0/me" -> *msgraph.User
user, err := graphClient.Me().Request().Get()
if err != nil { /*...*/ }
// Get current user's OneDrive root folder items
// "GET https://graph.microsoft.com/v1.0/me/drive/root/children" -> []msgraph.DriveItem
items, err := graphClient.Me().Drive().Root().Children().Request().Get()
if err != nil { /*...*/ }
// Create new group
// "POST https://graph.microsoft.com/v1.0/groups" -> *msgraph.Group
newGroup := &msgraph.Group{ /*...*/ }
createdGroup, err := graphClient.Groups().Request().Add(newGroup)
if err != nil { /*...*/ }
● メソッド呼び出しの連結で REST API の HTTP リクエストが出せる
レスポンスの JSON に対応するモデルの struct が返される

11. msgraph.go 使用法：REST API 対応コード
REST API msgraph.go 説明
GET /users users, err := cli.Users().Request().Get() 全ユーザー取得
POST /users
u := &msgraph.User{/*...*/}
user, err := cli.Users().Request().Add(u)
ユーザー作成
GET /users/XXX user, err := cli.Users().ID("XXX").Request().Get() ユーザー取得
PATCH /users/XXX
u := &msgraph.User{/*...*/}
err := cli.Users().ID("XXX").Request().Update(u)
ユーザー更新
DELETE /users/XXX err := cli.Users().ID("XXX").Request().Delete() ユーザー削除
● 各リソースコレクションの操作メソッドとモデル struct 定義が利用可能

12. msgraph.go 使用法：IDE による補完の活用
● REST API 仕様が Go 言語化されており IDE による補完が活用できる
● ただし Visual Studio Code は知恵熱を出して沈黙することがあり
たまに Restart Language Server する必要がある

13. msgraph.go アプリケーションの例：SharePoint ファイル共有アクセス
● SharePoint (OneDrive) ファイル共有のファイルを編集
● Microsoft Flow で CI ジョブ開始 msgraph.go でファイルをダウンロード
● ファイル共有上の Excel ブックの中身を直接編集する API もある

14. msgraph.go アプリケーションの例：msgraph-sshpubkey
● https://github.com/yaegashi/msgraph.go/tree/master/cmd/msgraph-sshpubkey
● SSH 公開鍵を User の extensions で管理できる (オープン拡張機能)
● sshd_config の AuthorizedKeysCommand で実行してユーザー認証
● サイズ 5.6MB の実行ファイルで導入が容易
AuthorizedKeysCommand /usr/bin/msgraph-sshpubkey -config /etc/msgraph-sshpubkey.json -login %u
AuthorizedKeysCommandUser root
$ cat /etc/msgraph-sshpubkey.json
{
"tenant_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"client_id": "YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY",
"client_secret": "ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
"login_map": {
"yaegashi": "yaegashi@l0wdev.onmicrosoft.com"
}
}

15. msgraph.go の実装

16. クライアントライブラリの実装戦略 = コード生成
● 膨大な MS Graph の機能をカバーするにはコード生成が必須
● OData v4 の REST API の定義 (XML) から自動生成する
● https://graph.microsoft.com/v1.0/$metadata
<EntityType Name="user" BaseType="microsoft.graph.directoryObject" OpenType="true">
<Property Name="userPrincipalName" Type="Edm.String" />
<Property Name="displayName" Type="Edm.String" />
<Property Name="passwordProfile" Type="microsoft.graph.passwordProfile" />
...
</EntityType>
<ComplexType Name="passwordProfile">
<Property Name="password" Type="Edm.String" />
<Property Name="forceChangePasswordNextSignIn" Type="Edm.Boolean" />
<Property Name="forceChangePasswordNextSignInWithMfa" Type="Edm.Boolean" />
</ComplexType>

17. 2 種類のコードジェネレータの存在
● MSGraph SDK Code Generator
https://github.com/microsoftgraph/MSGraph-SDK-Code-Generator
○ Microsoft 公式 MS Graph SDK コードジェネレータ
○ C# および .NET Framework による実装 (開発に Windows が必要)
○ C# (.NET Core), Java, JavaScript, Objective-C, Python
● msgraph.go コードジェネレータ
https://github.com/yaegashi/msgraph.go/gen
○ Pure Go による実装

18. なぜ MSGraph SDK Code Generator があるのに msgraph.go を？
● 実は MSGraph SDK Code Generator の存在を知らなかった
○ C# (.NET) 用のライブラリを参考に msgraph.go を作り始めて
しばらく経ってから気づいた
○ 現在の msgraph.go は MSGraph SDK Code Generator を
パクったリスペクトしたコード生成を行う
● MSGraph SDK Code Generator はクロスプラットフォームでない
○ 新しい言語の対応を追加するには Windows の開発環境が必要
○ C# よくわからない

19. msgraph.go のコード生成
● go generate ./gen
○ metadata XML のダウンロードとコード生成を行う
○ v1.0 と beta の 2 つの API バージョンのコードを生成する
○ text/template によりテンプレートファイルからコードを生成する
○ 生成したファイルに goimports を実行して整形・import 解決
package gen
//go:generate go run msgraph-download.go -pretty -baseURL https://graph.microsoft.com/v1.0 -out metadata-v1.0.xml
//go:generate go run msgraph-download.go -pretty -baseURL https://graph.microsoft.com/beta -out metadata-beta.xml
//go:generate go run msgraph-generate.go -baseURL https://graph.microsoft.com/v1.0 -in metadata-v1.0.xml -out ../v1.0
//go:generate go run msgraph-generate.go -baseURL https://graph.microsoft.com/beta -in metadata-beta.xml -out ../beta

20. msgraph.go の生成ファイル
種類 生成ファイル名 v1.0 beta
定数 <EnumType> 〜Enum.go 188 528
モデル <EntityType> <ComplexType> 〜Model.go 638 1684
リクエスト 〜Request.go 247 645
アクション <Action> 〜Action.go 59 134
合計 1132 2991
● 型名・メソッド名・ファイル名は C# (.NET) 版ライブラリに倣っている
● 生成ファイルの数が多すぎ？のため godoc.org で正しく表示できない

21. 生成コードの例：モデル struct の定義
type User struct {
DirectoryObject
UserPrincipalName *string `json:"userPrincipalName,omitempty"`
DisplayName *string `json:"displayName,omitempty"`
PasswordProfile *PasswordProfile `json:"passwordProfile,omitempty"`
/*...*/
}
type PasswordProfile struct {
Object
Password *string `json:"password,omitempty"`
ForceChangePasswordNextSignIn *bool `json:"forceChangePasswordNextSignIn,omitempty"`
ForceChangePasswordNextSignInWithMFA *bool `json:"forceChangePasswordNextSignInWithMfa,omitempty"`
}
● encoding/json の利用を前提としたフィールド名とタグがつけられる
● 基本型 (int, string, bool, etc.) や構造体はすべてポインタ型となる
● struct 埋め込みによりモデル継承、全モデルは Object struct をひとつ含む
struct埋め込み

22. JSON に含まれる追加データ
● API が返す JSON には、モデル struct のフィールドで定義されていない
"@odata.context" のような追加データが含まれることがよくある
● これらを単に encoding/json で Unmarshal すると失われてしまう
GET https://graph.microsoft.com/v1.0/me/
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"businessPhones": [],
"displayName": "八重樫 剛史",
"givenName": "剛史",
"jobTitle": null,
"mail": "yaegashi@l0wdev.onmicrosoft.com",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": "八重樫",
"userPrincipalName": "yaegashi@l0wdev.onmicrosoft.com",
"id": "6764eb11-841c-444e-b770-0e0d8748ea0a"
}

23. Object / AdditionalData / jsonx による追加データの対応
type Object struct {
AdditionalData map[string]interface{} `json:"-" jsonx:"true"`
}
func (o *Object) SetAdditionalData(key string, val interface{}) {/*...*/}
func (o *Object) GetAdditionalData(key string) (interface{}, bool) {/*...*/}
user, err := graphClient.Me().Request().Get()
if err != nil { /*...*/ }
if context, ok := user.GetAdditionalData("@odata.context"); ok {
fmt.Println(context)
// -> https://graph.microsoft.com/v1.0/$metadata#users/$entity
}
● Object の AdditionalData がいわゆる catch-all 動作で追加データを格納する
● encoding/json を改造・拡張した jsonx により実現
https://github.com/yaegashi/msgraph.go/tree/master/jsonx

24. まとめ

25. msgraph.go 開発の進捗と今後の計画
● これまでの進捗
○ Go 言語で簡単な Microsft Graph アプリが作成できる段階
● 今後の計画
○ 未対応機能実装：<Function>、バッチリクエスト、長時間操作、etc.
○ 開発インフラ整備：ユニットテスト、CI/CD
○ ドキュメント：godoc.org 使えん問題解決、Graph API ドキュメント
○ ライブラリ API の安定化

26. 公式コードジェネレータとの関わりについて
● Microsoft Graph SDKs - Requirements and Design
https://microsoftgraph.github.io/msgraph-sdk-design/
● 公式 MSGraph SDK Code Generator を Go 言語に対応させたい
○ 今後のライブラリの保守を考えると、公式コードジェネレータに Go に対応して
もらったほうが望ましいと思われる
○ msgraph.go のコード生成の経験 (jsonx とか) が生かせるはず

27. おわり
msgraph.go ぜひ使ってみてください
プルリクエストもお待ちしております！