Contenu connexe Similaire à Microsoft Graph APIを活用した社内アプリケーション開発 (20) Microsoft Graph APIを活用した社内アプリケーション開発8. 主なAPIの機能
• Azure Active Directory で管理されているO365のデータへのアクセス
• 具体的な操作例
対象 操作
ユーザー 取得 / 一覧表示 / 作成 / 更新 / 削除
予定表 取得 / 一覧表示 / 作成 / 更新 / 削除
➡イベント 取得 / 一覧表示 / 作成 / 更新 / 削除 / 通知ビュー / 会議日時検索
メール メッセージの取得 / 一覧表示 / 作成 / 送信 / メールボックス・フォルダの操作
組織階層 直属の部下の一覧表示 / マネージャーの取得、割り当て
連絡先 取得 / 一覧表示 / 作成 / フォルダ操作
写真 取得 / 更新
ディレクトリオブジェクト 所有、登録されているデバイスやオブジェクトの一覧表示、取得 / ライセンス割り当て / メンバーグループを取得、チェック
ドライブ 取得 / 一覧表示
グループの操作 予定表 / 会話 / 会話スレッド / ドライブ / 拡張プロパティ/ メモ / 写真 などの管理
多岐にわたるデータソース / 操作可能項目
ユーザー Outlook カレンダー OneNote オープン拡張機能
グループ Outlook メール OneDrive スキーマ拡張機能
Azure Active Directory 添付ファイル Excel Webhook
SharePoint 連絡先 Planner
9
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
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
12. 機能例1:ユーザープロフィール取得
Tristan
manager
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
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
Email
Documents
Contacts
Calendar
Tasks
Meetings
Sites
14
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": "ana@contoso.com"
}
],
"meetingDuration": "2h"
}
Trending
Documents
People I’m
working
with
Find me
the best
time to
meet Ana
Out of office
Search people
based on topics
Recent
Documents
15
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/notebooks
16
16. 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
17. 機能例4:バッチを利用し、1回に複数のリクエスト実行
• 1回のAPI呼び出しで
複数のリクエストが実行できます。
Batching
POST /$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"
}
]
}
Email
Documents
Contacts
Calendar
Tasks
Meetings
Sites
18
19. 機能例6:ユーザーやグループを拡張する
Open Extensions
GET /me/message/<id>/?$expand=extensions
{
"displayName": "Yina",
"extensions": [
{
"extensionName": "Com.Contoso.Referral",
"companyName": "Wingtip Toys",
"expirationDate": "2017-12-30T11",
"dealValue": 10,000
}
]
}
Schema extensions
POST /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
22. 社内分析レポート
• 日次・週次で Graph から情報を取り出して分析、ダッシュボードで見える化
• ミーティングの参加記録や、社員コラボレーションの情報、稼働率を把握可能
• 分析内容に合わせて特定の社員に通知を送る
Notification Hub
App Services / Functions
社員端末にプッシュ通知を送る 社員端末にメール通知を送る
Machine Learningで分析 Power BIでダッシュボート表示
23
23. リアルタイムの社内リソース活用
• リアルタイムに Graph から情報を取り出して分析、ダッシュボードで見える化
• 会議室の有効活用やレコメンデーション、社員の稼働などをチェックしレポート
• 特定の社員にアラートやレコメンデーションを送る
Notification Hub
App Services/ Functions
社員端末にプッシュ通知を送る メール通知を送る
Machine Learningで分析
Power BIでダッシュボート表示Service Busと
Streaming Analyticsで
リアルタイム処理
24
24. 社内情報アクセスの簡易化
• Chat Botのインタフェースを使い社内情報にアクセス
• 会議室の予約やメール送信の簡易化で、社員のコラボレーションを活性化
• 参加社員の空き時間を調整し、自動でミーティングをセット
App Services / Functions
ボットにメッセージを送る
Bot Frameworkで
クライアントとアプリの連携
機動性の高い
クラウドアプリケーションで内部処理
Graph APIにアクセスし情報を取得
・カレンダー
・グループ / チーム
・タスクリスト
・インサイト
25実装例:秘書ボット
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
32. パーミッションの設定
• パーミッションは Application Permissions と Delegated Permissionsがあり
ます。両方設定することもできますが、必要最低限のパーミッションにチェックを入れま
しょう。
Application Permissionの項目 Delegated Permissionの項目
33
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
34. マルチテナントの設定
• プロパティメニューより マルチテナントを Yes にします。
• 外部組織のユーザが、組織のディレクトリのデータへのアクセスをアプリに許可できるか
どうかを指定します。このコントロールの影響を受けるのは、アクセスを許可する機能
のみです。すでに許可されているアクセスについては影響ありません。
35
38. 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
42. ユーザーの作成後、アクセスができない
• ユーザーは、ユーザー エンティティの POST ですぐに作成できます。
• Office 365 サービスにアクセスするには、まず Office 365 ライセンスをユーザーに
割り当てる必要があります。
• それでも、サービスが分散しているという性質上、Microsoft Graph API を介して
このユーザーがファイル、メッセージ、イベント エンティティを使用できるようになるまで
15 分かかる場合があります。
• この間、アプリには HTTP 404 エラー応答が送られてきます。
43
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
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
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
47. JSON バッチ処理の注意事項
✓ 入れ子状のバッチ不可
JSON のバッチ要求には、入れ子になったバッチは一切含めることはできません。
✓ 個々の要求はすべて同期要求とします。
バッチ要求に含まれるすべての要求は同期して実行する必要があります。存在する場合、respond-async の設定は無視されます。
✓ トランザクション未対応
Microsoft Graph は現段階では個々の要求のトランザクション処理をサポートしていません。個々の要求で atomicityGroup プロパティを指定しても
無視されます。
✓ URI は相対 URI である必要があります。
バッチ要求では、必ず相対 URI を指定してください。Microsoft Graph はバッチ要求の URL に含まれているバージョン エンドポイントを使い、これらを
絶対 URL に変換します。
✓ バッチ サイズの制限
現段階では、JSON バッチ要求は 5 つまでの個別要求に限られています。JSON バッチ処理が完成に近づくにつれて、この制限を緩和します。
48
48. クエリ パラメーターの制限事項
✓ $expand の制限:
nextLink はサポートされていません
1 レベルを超える展開はサポートされていません
余分なパラメーターはサポートされていません ($filter、$select)
✓ 複数の名前空間はサポートされていません
✓ $ref の GET とキャストはユーザー、グループ、デバイス、サービス プリンシパル、アプリケーションではサポートされていません。
✓ @odata.bind はサポートされていません。つまり、開発者は Accepted や RejectedSenders を適切にグループに設定することができません。
✓ @odata.id は最低限のメタデータを使用する場合、非包含構造のナビゲーション (メッセージなど) には存在しません
✓ ワークロード間でのフィルター/検索は利用できません。
✓ フルテキスト検索 ($search を使用した検索) はメッセージなどのいくつかのエンティティに対してのみ使用できます。
49
49. 本書に記載した情報は、本書各項目に関する発行日現在の Microsoft の見解を表明するものです。Microsoftは絶えず変化する市場に対応しなければならないため、ここに記載した情報に対していかなる責務を負うものではなく、提示された
情報の信憑性については保証できません。
本書は情報提供のみを目的としています。 Microsoft は、明示的または暗示的を問わず、本書にいかなる保証も与えるものではありません。
すべての当該著作権法を遵守することはお客様の責務です。Microsoftの書面による明確な許可なく、本書の如何なる部分についても、転載や検索システムへの格納または挿入を行うことは、どのような形式または手段(電子的、機械的、複
写、レコーディング、その他)、および目的であっても禁じられています。これらは著作権保護された権利を制限するものではありません。
Microsoftは、本書の内容を保護する特許、特許出願書、商標、著作権、またはその他の知的財産権を保有する場合があります。Microsoftから書面によるライセンス契約が明確に供給される場合を除いて、本書の提供はこれらの特許、商標、
著作権、またはその他の知的財産へのライセンスを与えるものではありません。
© 2017 Microsoft Corporation. All rights reserved.
Microsoft, Windows, その他本文中に登場した各製品名は、Microsoft Corporation の米国およびその他の国における等力商標または商標です。
その他、記載されている会社名および製品名は、一般に各社の商標です。