microsoft graph apiを活用した社内アプリケーション開発
TRANSCRIPT
アプリケーションのユーザー体験を加速
• シンプルなREST APIへのアクセスをアプリケーションに追加するだけで、アプリケーションの幅が広がります。
Users Groups Outlook Calendar SharePointExcel IntuneTeams Azure ADOneNote Planner
https://graph.microsoft.com
アプリケーションひとつのエンドポイントひとつのトークン
➡ すべてのユーザー
5
Microsoft Graph APIでアプリに様々な機能を追加可能
ビジネスプロセスの効率化スマートミーティング カスタムダッシュボード
スマートピッカー Graph連携Bot デバイスとの連携
6
コンプライアンスとリージョン
• Microsoft Graph APIはすべての Office 365、 Azure リージョンで利用可能です。
• コンプライアンスや法律もそれぞれのリージョンに従います。 つまり、日本の場合は日本の法律を準拠法とし、管轄裁判所は東京地裁裁判所になります。
7
主なAPIの機能
• Azure Active Directory で管理されているO365のデータへのアクセス
• 具体的な操作例対象 操作
ユーザー 取得 / 一覧表示 / 作成 / 更新 / 削除
予定表 取得 / 一覧表示 / 作成 / 更新 / 削除
➡イベント 取得 / 一覧表示 / 作成 / 更新 / 削除 / 通知ビュー / 会議日時検索
メール メッセージの取得 / 一覧表示 / 作成 / 送信 / メールボックス・フォルダの操作
組織階層 直属の部下の一覧表示 / マネージャーの取得、割り当て
連絡先 取得 / 一覧表示 / 作成 / フォルダ操作
写真 取得 / 更新
ディレクトリオブジェクト 所有、登録されているデバイスやオブジェクトの一覧表示、取得 / ライセンス割り当て / メンバーグループを取得、チェック
ドライブ 取得 / 一覧表示
グループの操作 予定表 / 会話 / 会話スレッド / ドライブ / 拡張プロパティ/ メモ / 写真 などの管理
多岐にわたるデータソース / 操作可能項目
ユーザー Outlook カレンダー OneNote オープン拡張機能
グループ Outlook メール OneDrive スキーマ拡張機能
Azure Active Directory 添付ファイル Excel Webhook
SharePoint 連絡先 Planner
9
アクセス権限
委任されたアクセス許可
• サインインしているユーザーが存在するアプリで使用します。これに該当するアプリの場合は、ユーザーまたは管理者がアプリの要求するアクセス許可に同意します。アプリには、Microsoft Graph の呼び出し時に、サインインしているユーザーとして動作するためのアクセス許可が委任されます。一部の委任されたアクセス許可は非管理ユーザーの同意によって付与されますが、高度な特権が付与されるアクセス許可には管理者の同意が必要になります。
アプリケーションのアクセス許可
• サインインしているユーザーが存在しないアプリで使用します。たとえば、バックグラウンド サービスやデーモンなどのアプリです。アプリケーションのアクセス許可は、管理者のみが同意できます。
10
バージョンと機能複数のバージョンが利用可能です。
GA ( v1.0 ) プレビュー ( beta )
Azure Active Directory
Outlook mail, calendar and contacts
Office 365 groups and conversations
OneDrive drives and files
Excel
Planner
OneNote
SharePoint Sites
People
Microsoft Teams
Insights (powering Delve)*
SharePoint Lists
Outlook Tasks
Intune
Office 365 Reporting
AD Administrative Units
Project Rome
11
APIの呼び出し方
HTTPのリクエストメソッド : GET | POST | PATCH | PUT | DELETE
Version : /v1.0 or /beta
Resource : /users, /groups, /sites, /drives, /devices, more…
Id : /users/AAA
Property : /users/AAA/department
ナビゲーションを介して関連リソースへ移動: /users/AAA/events
Query-parameters: /users/AAA/events?$top=5
フォーマット変更: $select | $orderby
結果をコントロール: $filter | $expand
ページング: $top | $skip | $skiptoken
/{version} ?{query-parameters}/{resource} /{id} /{property}
12
機能例1:ユーザープロフィール取得
Tristanmanager
Dmitry Matt Sudhi
directReports
Groups
memberOf
GET: /users/yina{
"displayName": "Yina", "jobTitle": "PRINCIPAL PM MANAGER",
}
GET: /users/yina/photo/…{}
GET: /users/yina/manager{"displayName": "Tristan", …}
GET: /users/yina/directReports"value" : [
{"displayName": "Matt", …},{"displayName": "Dmitry", …},
]
GET: /me/memberOf/…"value" : [
{"displayName": "Office engineering", …},{"displayName": "Women in tech", …},
]
13
機能例2:ユーザー関連コンテンツの取得
GET /me/drive/root/…"value" : [
{"name": "proposal.pptx",… },{"name": "forecast.xlsx",… }
]
GET /drives/items/{id}/workbook
GET /me/messages
GET /me/events
GET /me/contacts
GET /me/onenote/notebooks
GET /me/planner/tasks
GET /me/devices
GET /sites:/teams/opg:/
GET /sites:/teams/opg:/lists
GET /groups/{id}/conversations
Documents
Contacts
Calendar
Tasks
Meetings
Sites
14
機能例3:アクティビティベースのインサイト
GET /me/insights/trending"value" : [
{"name": "presentation.pptx", …},{"name": "forecast.xlsx", …}
]
GET /me/drive/recent"value" : [
{"name": "guidelines.pptx", …},{"name": "budget.xlsx", …}
]
GET people/?$search="topic: planning""value" : [
{"displayName": "Dan", …},{"displayName": "Sean", …},
]
POST: /me/findMeetingTimes{
"attendees": [ {
"type": "required", "emailAddress": {
"address": "[email protected]" }
], "meetingDuration": "2h"
}
TrendingDocuments
People I’m working with
Find me the best time to meet Ana
Out of office
Search people based on topics
RecentDocuments
15
代表的なクエリ
Scenario API - https://graph.microsoft.com/
GET my profile /v1.0/me
GET my files /v1.0/me/drive/root/children
GET my photo /v1.0/me/photo/$value
GET my high importance email /v1.0/me/messages?$filter=importance eq 'high'
GET my calendar /v1.0/me/calendar
GET my manager /v1.0/me/manager
GET last user to modify foo.txt /v1.0/me/drive/root/children/foo.txt/lastModifiedByUser
GET my recent files /v1.0/me/drive/recent
GET Office 365 groups I’m member of /v1.0/me/memberOf/$/?$filter=groupTypes/any(a:a eq 'unified')
GET users in my organization /v1.0/users
GET group conversations /v1.0/groups/<id>/conversations
GET people relevant to me /beta/me/people
GET files trending around me /beta/me/insights/trending
GET the root SharePoint site /beta/sharepoint/sites/root
GET my Planner tasks /beta/me/planner/tasks
GET my notes /beta/me/onenote/notebooks16
Microsoft Graph APIの機能例
• 各種SDKやWebook、バッチ実行の機能が追加されています。
Generally Available ( v1.0 ) Preview ( beta )
Webhooks for OneDrive and Outlook
Delta query for OneDrive
SDKs for .Net/Xamarin and Android
SDKs for JS/Node and PHP
AppOnly webhooks for Outlook
Delta query for AAD and Outlook
Extend Graph with your own data
SDKs for iOS, Python, Ruby
Hybrid on-premise support for Outlook (config wizard support)
Webhooks for users and groups
Webhooks for Outlook consumer
Delta query scoping filter for AAD
Batching
17
機能例4:バッチを利用し、1回に複数のリクエスト実行
• 1回のAPI呼び出しで複数のリクエストが実行できます。
BatchingPOST /$batch{
"requests": [{"id": "1","url": "/me/drive/root/children","method": "POST","body": {
"name": "folder1","folder": {}
},"headers": {
"content-type": "application/json"}
}, {"id": "2","url": "/me/drive/root/children/folder1","method": "GET","dependsOn": ["1"]
}, {"id": "3","method": "GET","url": "/me/planner/tasks"
}, {"id": "4","method": "GET","url": "/groups/{id}/events"
}]}
Documents
Contacts
Calendar
Tasks
Meetings
Sites
18
機能例5:通知機能と変更のトラッキング
GET/me/mailFolders/{id}/messages/delta"@odata.deltalink":"me/mailfolders('AA')/messages/delta?$deltatoken=BB","value" : […]
POST /subscriptions{"changeType": "created,updated", "notificationUrl": "https://app.net/callback","resource": "/me/mailfolders('AA')/messages",
}
GET/me/mailFolders/{id}/messages/delta ?$deltatoken=BB""value" : […]
Edited a file
Got a new hire
Added a new member to a group
Scheduled a new meeting
Got high important email
19
機能例6:ユーザーやグループを拡張する
Open ExtensionsGET /me/message/<id>/?$expand=extensions{"displayName": "Yina", "extensions": [
{"extensionName": "Com.Contoso.Referral","companyName": "Wingtip Toys","expirationDate": "2017-12-30T11","dealValue": 10,000
}]
}
Schema extensionsPOST /schemaExtensions{
"id": "training_courses", "targetTypes": [ "Group" ],"properties": [
{"name": "courseName","type": "String"
}…]
}
GET /groups?$filter=courses/name eq Math101
Customer referral email
Carlo’s son: Johnny
Favorite color: blue
Group: Math 101
20
社内分析レポート• 日次・週次で Graph から情報を取り出して分析、ダッシュボードで見える化
• ミーティングの参加記録や、社員コラボレーションの情報、稼働率を把握可能
• 分析内容に合わせて特定の社員に通知を送る
Notification Hub
App Services / Functions
社員端末にプッシュ通知を送る 社員端末にメール通知を送る
Machine Learningで分析 Power BIでダッシュボート表示
23
リアルタイムの社内リソース活用• リアルタイムに Graph から情報を取り出して分析、ダッシュボードで見える化
• 会議室の有効活用やレコメンデーション、社員の稼働などをチェックしレポート
• 特定の社員にアラートやレコメンデーションを送る
Notification Hub
App Services/ Functions
社員端末にプッシュ通知を送る メール通知を送る
Machine Learningで分析
Power BIでダッシュボート表示Service BusとStreaming Analyticsでリアルタイム処理
24
社内情報アクセスの簡易化• Chat Botのインタフェースを使い社内情報にアクセス
• 会議室の予約やメール送信の簡易化で、社員のコラボレーションを活性化
• 参加社員の空き時間を調整し、自動でミーティングをセット
App Services / Functions
ボットにメッセージを送るBot Frameworkでクライアントとアプリの連携
機動性の高いクラウドアプリケーションで内部処理
Graph APIにアクセスし情報を取得・カレンダー・グループ / チーム・タスクリスト・インサイト
25実装例:秘書ボット
社内プロフィールの充実によるコラボレーション活性化
• 社員のプロフィール情報、参加プロジェクト情報を充実させ、チーム間のコラボレーションが生まれやすい環境を整備する。
• 機械学習を利用し、統計をコラボレーションに活用
App Services / Functions
定期的にユーザーデータの取得、分析し不足しているユーザー情報をリスト化、管理必要なプロファイルを充実させるように社員へ通知
アプリケーションからMicrosoft Graph APIを参照し、コラボレーション機能、レコメンデーション機能を追加
26
Powered by Azure
社内情報の英語化、日本語化と検索
• 社内に散らばる英語情報、日本語情報を翻訳し、検索可能にする
• 社内資料をクローリングし、英語の資料があった場合、
• Microsoft Translator APIで日本語化し、DBに保存。
• Azure Search を用いてインデクシング、検索可能な状態へ
27
Web Jobsでデータを定期的に取得
翻訳したデータをDBに保存、Azure Search でインデクシング
Web AppsなどのWebアプリ、クライアントアプリから日本語化されたデータを取得
マイクロソフトの人工知能
Cognitive Services
人間の認知機能の一部をコンピューター演算モデル化し、API
経由でそれらのモデルを利用することができるサービスです。
✓マシーンラーニングベースのインテリジェンスを活用してユーザー
エクスペリエンスを高めるツールにより、やり取りを自然かつ状
況に応じて行うことができるようにします。
✓マイクロソフトが培ってきた視覚、音声、言語、および知識に
関する、強力な人工知能アルゴリズムのコレクションが活用で
きます。
28
29
視覚顔、画像、感情認識などのスマートな洞察を返すことにより、コンテンツを自動でモデレートし、アプリケーションをさらにパーソナライズする最先端の画像処理アルゴリズム。
音声アプリケーション内で音声言語を処理
言語アプリケーションが自然言語を処理し、センチメントとトピックを評価して、ユーザーの欲しいものを認識する方法を学習できるようにします。
知識合理的なレコメンデーションやセマンティック検索などのタスクを行うことができるように、複雑な情報とデータをマッピングします。
検索Bing Search API との連携を深めて、アプリや Web ページ、その他の機能をもっと使いやすくしましょう。
Cognitive Services
AAD アプリケーションの登録をします
• Azure Portal > Azure Active Directory > App registrations
• [ + New application registration ]を押します。
31
アプリケーションを作成• 任意のアプリ名とアプリケーションタイプ 、sign-on URLを入力します。
• Sign-on URL:https://www.getpostman.com/oauth2/callback (PostmanのCall Back URL)
• アプリケーションタイプ: Web app / API
• 作成されたら Application ID はメモしておきましょう。
• 次に[ Required permission ]からパーミッション設定をします。今回はMicrosoft Graph を選択しましょう。
32
パーミッションの設定
• パーミッションは Application Permissions と Delegated Permissionsがあります。両方設定することもできますが、必要最低限のパーミッションにチェックを入れましょう。
Application Permissionの項目 Delegated Permissionの項目
33
アクセス許可についてMicrosoft Graph で People API を呼び出すには、アプリに適切なアクセス許可が必要になります。
様々な権限があります。以下に例を示します。
People.Read
• https://graph.microsoft.com/v1.0/me/people/
• 上記リクエストは一般的な People API の呼び出しの例です。自分に関連するユーザーを取得します。
• 呼び出しのためにはPeople.Read.Allの権限が必要です。
• People.Read には、エンド ユーザーの同意が必要です。
People.Read.All
• https://graph.microsoft.com/v1.0/users/{id}/people
• 例えば上記リクエストの呼び出しでは、特定のユーザーに最も関連性のあるユーザーを取得します。
• 呼び出しのためにはPeople.Read.Allの権限が必要です。
• People.Read.All には、管理者の承認が必要です。
参考ページ:https://msdn.microsoft.com/ja-jp/library/azure/ad/graph/howto/azure-ad-graph-api-permission-scopes
34
マルチテナントの設定
• プロパティメニューより マルチテナントを Yes にします。
• 外部組織のユーザが、組織のディレクトリのデータへのアクセスをアプリに許可できるかどうかを指定します。このコントロールの影響を受けるのは、アクセスを許可する機能のみです。すでに許可されているアクセスについては影響ありません。
35
シークレットの設定をします
• パーミッションの設定が出来たらアクセスのためのシークレットを作成しましょう。任意の値を VALUE に入力し、[Save]を押すとシークレットが生成されます。このシークレットはメモしておきましょう。
36
Bearer トークンを取得するための
• 先ほどのアプリケーションIDとシークレットを入力します。
• ログインが求められ、成功するとトークンが取得できます。
項目名 入力値
Token Name 任意の名前
Auth URL https://login.windows.net/common/oauth2/authorize?resource=https%3A%2F%2Fgraph.microsoft.com
Access Token URL https://login.windows.net/common/oauth2/token
Client ID アプリケーションID
Client Secret 作成したシークレット
Grant Type Authorization Code
39
ユーザーの作成後、アクセスができない
• ユーザーは、ユーザー エンティティの POST ですぐに作成できます。
• Office 365 サービスにアクセスするには、まず Office 365 ライセンスをユーザーに割り当てる必要があります。
• それでも、サービスが分散しているという性質上、Microsoft Graph API を介してこのユーザーがファイル、メッセージ、イベント エンティティを使用できるようになるまで15 分かかる場合があります。
• この間、アプリには HTTP 404 エラー応答が送られてきます。
43
写真の制限
• ユーザーのプロフィール写真の読み取りと更新は、ユーザーがメールボックスを持っている場合にのみ使用できます。
• さらに、以前 thumbnailPhoto プロパティを使用して (Office 365 統合 API のプレビュー、または Azure AD Graph、AD 接続同期を使用して) 保存されたいかなる写真もユーザー リソースの Microsoft Graph の写真**プロパティを使用してアクセスできなくなります。
• 写真の読み取りまたは更新が失敗すると、この例では次のエラーが発生します。
44
グループと Microsoft Teams のアクセス許可✓Microsoft Graph では、グループと Microsoft Teams API にアクセスするために 2 つのアクセス許可
(Group.Read.All と Group.ReadWrite.All) を公開します。
✓これらのアクセス許可は、管理者による同意が必要です (これがプレビューとの違いです)。将来的には、ユーザーが同意するグループとチームのための新しいアクセス許可を追加する予定です。
✓また、コア グループの管理とマネージメントのための API だけが、委任されたアクセス許可とアプリ専用のアクセス許可によるアクセスをサポートします。グループ API の他のすべての機能は、委任されたアクセス許可のみサポートします。
Application Permission / Delegated Permissionをサポートするグループの機能の例
✓ グループの作成と削除
✓ グループの管理とマネージメントに関するグループ プロパティの取得と更新
✓ グループのディレクトリ設定、型、同期
✓ グループの所有者とメンバーシップ
Delegated Permission をサポートするグループ機能の例
✓ グループの会話、イベント、写真
✓ 外部の送信者、承認済みまたは拒否された送信者、グループのサブスクリプション
✓ ユーザーのお気に入り、見えないカウント
✓ Microsoft Teams チャンネルおよびチャット。
45
共有された予定表にアクセスする/users/{user_id}/calendars/{calendar_id}/events
上記のエンドポイントにアクセスするとエラー コード ErrorInternalServerTransientError で HTTP 500 を受け取る可能性があります。
理由はカレンダーの共有においては、 “古い” アプローチと“新しい” アプローチの2つの実装のされ方があるからです。各条件は以下です。
• 新しいアプローチは、表示または編集のアクセス許可による予定表の共有に使用できますが、委任のアクセス許可には使用できません。
• 予定表が新しいアプローチによって共有されている場合のみ、予定表 REST API を使用して、共有された予定表を表示または編集できます。
• 予定表が古いアプローチによって共有されている場合、予定表 REST API を使用して、このような予定表を表示または編集することはできません。
予定表が表示または編集のアクセス許可で共有されていても、古いアプローチを使用している場合、エラーを回避して手動で予定表共有をアップグレードし、新しいアプローチを使用することができます。時間の経過とともに、Outlook では共有されているすべての予定表が、委任アクセス許可で共有されている予定表を含め、新しいアプローチを使用できるように自動的にアップグレードされます。 新しいアプローチを使用できるように共有されている予定表を手動でアップグレードするには、以下の手順を実行します。
1. 受信者は、それまで共有されていた予定表を削除します。
2. 予定表の所有者は、Outlook on the web、iOS 版 Outlook または Android 版 Outlook で予定表を再共有します。
3. 受信者は Outlook on the web を使用して共有された予定表を再度受け取ります。(まもなくその他の Outlook クライアントも使用可能になります)
4. 受信者は、新しいアプローチを使用して iOS 版 Outlook または Android 版 Outlook で共有されている予定表を表示可能にすることで、予定表が正しく再共有されていることを確認します。
新しいアプローチで共有した予定表は、全く別の予定表のようにメールボックスで表示されます。
共有された予定表では、予定表 REST API を使用して自分の予定表のようにイベントを表示または編集できます。次のようにアクセスすることができます。
/me/calendars/{calendar_id}/events
46
代表的なクエリパラメータ$skip : ページネーション
• 人物の参照要求では、サインインしているユーザー (/me) と最も関連性の高い人物を取得します。既定では、応答ごとに 10 件のレコードが返されますが、これは $top と $skip のパラメータを使用して 2 番目の要求を行うことができます。前の要求に追加情報が含まれている場合は、次の要求でサーバーから人物についての後続ページを取得します。
• 次の例は応答を示しています。既定では、各応答は 10 個のレコードを返します。これは $top クエリ パラメーターを使用して変更できます。この例では $top を使用して 3 つのレコードへの応答を制限しています。
• GET https://graph.microsoft.com/v1.0/me/people/?$top=3&$skip=10
$orderby : 応答の並べ替え
• 既定では、応答に含まれる人物は、クエリとの関連性で並べ替えられます。応答に含まれる人物の順序は、$orderby パラメーターを使用することで変更できます。
• 下記のクエリでは、自分に最も関連のある人物を選択し、その人物を displayName で並べ替えてから、最初の 10 人の人物を並べ替え済みのリストで返します。
• GET https://graph.microsoft.com/v1.0/me/people/?$orderby=displayName
$top : 返される人物の数とフィールド数の変更
• 応答で返される人物の数は、$top パラメーターを設定することで変更できます。
• 次に示す例では、/me に最も関連のある 1,000 人の人物を要求します。また、この要求では、人物の displayName のみを要求することで、サーバーから返されるデータの量も制限しています。
• GET https://graph.microsoft.com/v1.0/me/people/?$top=1000&$Select=displayName
$filter : フィルターを使用した応答の制限
• $filter パラメーターを使用すると、指定した条件に等しいレコードを持つ人物のみに応答を制限できます。
• 次のクエリは、class として person、subclass として organizationUser が割り当てられている personType プロパティを持つ person インスタンスへの応答を制限します。
• GET https://graph.microsoft.com/v1.0/me/people/?$filter=personType/class eq 'Person' and personType/subclass eq 'OrganizationUser’47
JSON バッチ処理の注意事項✓入れ子状のバッチ不可
JSON のバッチ要求には、入れ子になったバッチは一切含めることはできません。
✓個々の要求はすべて同期要求とします。
バッチ要求に含まれるすべての要求は同期して実行する必要があります。存在する場合、respond-async の設定は無視されます。
✓トランザクション未対応
Microsoft Graph は現段階では個々の要求のトランザクション処理をサポートしていません。個々の要求で atomicityGroup プロパティを指定しても
無視されます。
✓URI は相対 URI である必要があります。
バッチ要求では、必ず相対 URI を指定してください。Microsoft Graph はバッチ要求の URL に含まれているバージョン エンドポイントを使い、これらを
絶対 URL に変換します。
✓バッチ サイズの制限
現段階では、JSON バッチ要求は 5 つまでの個別要求に限られています。JSON バッチ処理が完成に近づくにつれて、この制限を緩和します。
48
クエリ パラメーターの制限事項
✓ $expand の制限:
nextLink はサポートされていません
1 レベルを超える展開はサポートされていません
余分なパラメーターはサポートされていません ($filter、$select)
✓ 複数の名前空間はサポートされていません
✓ $ref の GET とキャストはユーザー、グループ、デバイス、サービス プリンシパル、アプリケーションではサポートされていません。
✓ @odata.bind はサポートされていません。つまり、開発者は Accepted や RejectedSenders を適切にグループに設定することができません。
✓ @odata.id は最低限のメタデータを使用する場合、非包含構造のナビゲーション (メッセージなど) には存在しません
✓ ワークロード間でのフィルター/検索は利用できません。
✓ フルテキスト検索 ($search を使用した検索) はメッセージなどのいくつかのエンティティに対してのみ使用できます。
49
本書に記載した情報は、本書各項目に関する発行日現在の Microsoft の見解を表明するものです。Microsoftは絶えず変化する市場に対応しなければならないため、ここに記載した情報に対していかなる責務を負うものではなく、提示された
情報の信憑性については保証できません。
本書は情報提供のみを目的としています。 Microsoft は、明示的または暗示的を問わず、本書にいかなる保証も与えるものではありません。
すべての当該著作権法を遵守することはお客様の責務です。Microsoftの書面による明確な許可なく、本書の如何なる部分についても、転載や検索システムへの格納または挿入を行うことは、どのような形式または手段(電子的、機械的、複
写、レコーディング、その他)、および目的であっても禁じられています。これらは著作権保護された権利を制限するものではありません。
Microsoftは、本書の内容を保護する特許、特許出願書、商標、著作権、またはその他の知的財産権を保有する場合があります。Microsoftから書面によるライセンス契約が明確に供給される場合を除いて、本書の提供はこれらの特許、商標、
著作権、またはその他の知的財産へのライセンスを与えるものではありません。
© 2017 Microsoft Corporation. All rights reserved.
Microsoft, Windows, その他本文中に登場した各製品名は、Microsoft Corporation の米国およびその他の国における等力商標または商標です。
その他、記載されている会社名および製品名は、一般に各社の商標です。