Microsoft Graph 内を移動してデータとメソッドにアクセスする
Microsoft Graph APIを使用してデータの読み取りと書き込みを行うだけでなく、さまざまな要求パターンを使用して Microsoft Graph のリソースを走査できます。 メタデータ ドキュメントは、Microsoft Graph のリソースとリレーションシップのデータ モデルを理解するのにも役立ちます。
Microsoft Graph API メタデータ
メタデータ ドキュメント ($metadata) が、サービス ルートに公開されます。 次の URL を使用して、Microsoft Graph APIの v1.0 およびベータ版のサービス ドキュメントを表示できます。
Microsoft Graph API v1.0 メタデータ
https://graph.microsoft.com/v1.0/$metadata
Microsoft Graph API beta メタデータ
https://graph.microsoft.com/beta/$metadata
メタデータにより、要求および応答パケットが表すリソースを構成するエンティティの種類、複合型、列挙型を含む、Microsoft Graph のデータ モデルを参照し、理解することができます。
メタデータでは、対応する OData 名前空間での種類、メソッド、および列挙型の定義もサポートされています。 Microsoft Graph API の大部分は、OData 名前空間 microsoft.graph で定義されます。 いくつかの API は、サブネームスペース (例: microsoft.graph.callRecords) で定義されています。
メタデータを使用して、Microsoft Graph のエンティティ間のリレーションシップを学ぶことができ、また、それらのエンティティ間を移動する URL を作成することができます。
注:
- リソース ID の大文字と小文字の区別 は、Microsoft Graph API から返されたものと同じものを使用します。
- リソース ID、ユーザーが割り当てる値、およびその他の base-64 でエンコードされた値は、大文字と小文字が区別されるものと考えてください。
- パス URL リソース名、クエリパラメーター、アクション名、関数名、API プロパティ名と値を含むそれらのリクエスト本文パラメーターは、大文字と小文字を区別しないものと考えてください。
リソースのコレクションを表示する
Microsoft Graph では、HTTP GET クエリを使用してテナント内のリソースを表示することができます。 クエリの応答には、各リソースのプロパティが含まれます。 各エンティティ リソースはそれぞれの ID によって識別されます。 リソース ID の形式は、通常、リソースの種類によって異なります。
たとえば、テナント内で定義されている user リソースのコレクションを取得できます。
成功すると、ペイロード内の ユーザー リソースのコレクションを含む 200 OK 応答が返されます。 各ユーザーは id プロパティで識別され、既定のプロパティが伴います。 以下に示すペイロードは、簡潔にするために切り捨てられます。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
"value":[
{
"id":"f71f1f74-bf1f-4e6b-b266-c777ea76e2c7",
"businessPhones":[
],
"displayName":"CIE Administrator",
"givenName":"CIE",
"jobTitle":null,
"mail":"admin@contoso.com",
"mobilePhone":"+1 3528700812",
"officeLocation":null,
"preferredLanguage":"en-US",
"surname":"Administrator",
"userPrincipalName":"admin@contoso.com"
},
{
"id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
"businessPhones":[
],
"displayName":"Alan Steiner",
"givenName":"Alan",
"jobTitle":"VP Corporate Marketing",
"mail":"alans@contoso.com",
"mobilePhone":null,
"officeLocation":null,
"preferredLanguage":"en-US",
"surname":"Steiner",
"userPrincipalName":"alans@contoso.com"
}
]
}
Microsoft Graph では、あるリソースのリレーションシップを別のリソースと移動することで、コレクションを表示することもできます。 たとえば、ユーザーの mailFolders ナビゲーション プロパティを使用して、ユーザーのメールボックス内の mailFolder リソースのコレクションを照会できます。
GET https://graph.microsoft.com/v1.0/me/mailfolders HTTP/1.1
Authorization : Bearer {access_token}
成功すると、ペイロード内の mailFolder リソースのコレクションを含む 200 OK 応答が返されます。 各 mailFolder は id プロパティによって識別され、そのプロパティが伴います。 以下に示すペイロードは、簡潔にするために切り捨てられます。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('16f5a7b6-5a15-4568-aa5a-31bb117e9967')/mailFolders",
"value":[
{
"id":"AAMkADRm9AABDGisXAAA=",
"displayName":"Archive",
"parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
"childFolderCount":0,
"unreadItemCount":0,
"totalItemCount":0
},
{
"id":"AQMkADRm0AAAIBXAAAAA==",
"displayName":"Sales reports",
"parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
"childFolderCount":0,
"unreadItemCount":0,
"totalItemCount":0
},
{
"id":"AAMkADRCxI9AAAT6CAIAAA=",
"displayName":"Conversation History",
"parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
"childFolderCount":1,
"unreadItemCount":0,
"totalItemCount":0
}
]
}
ID ごとにコレクションから特定のリソースを表示する
Microsoft Graph のほとんどのエンティティでは、 ID が主キーです。
引き続き例として user を使用します。ユーザーに関する情報を表示するには、HTTPS GET 要求を使用してユーザーの ID から特定のユーザーを取得します。 user エンティティでは、id プロパティまたは userPrincipalName プロパティのいずれかを識別子として使用できます。
次の要求の例では、ユーザーの ID として userPrincipalName の値を使用しています。
GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com HTTP/1.1
Authorization : Bearer {access_token}
成功した場合は、200 OK 応答が返され、そのペイロードに、次に示すようなユーザー リソースの表現が含まれています。
HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 982
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"id": "c95e3b3a-c33b-48da-a6e9-eb101e8a4205",
"city": "Redmond",
"country": "USA",
"department": "Help Center",
"displayName": "John Doe",
"givenName": "John",
"userPrincipalName": "john.doe@contoso.com",
...
}
別のキーを使用してコレクションから特定のリソースを表示する
一部のエンティティでは、主キー ID の代わりにオブジェクトを取得するために使用できる代替キーがサポートされています。 たとえば、 application エンティティと servicePrincipal エンティティでは 、appId 代替キーがサポートされています。
次の例では、代替キー構文を使用して 、appId によってサービス プリンシパルを取得します。
GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000') HTTP/1.1
Authorization : Bearer {access_token}
リソースの特定のプロパティの読み取り
ユーザーから提供された自己紹介の記述やスキル セットなどのユーザーの個人データのみを取得するには、次の例に示したように、以前の要求に $select クエリ パラメーターを追加することができます。
GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com?$select=displayName,aboutMe,skills HTTP/1.1
Authorization : Bearer {access_token}
成功した場合の応答は、200 OK 状態と、次に示すペイロードを返します。
HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 169
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"aboutMe": "A cool and nice guy.",
"displayName": "John Doe",
"skills": [
"n-Lingual",
"public speaking",
"doodling"
]
}
ここでは、user エンティティのプロパティ セット全体ではなく、aboutMe、displayName、skills という基本的なプロパティのみが返されます。
プロパティ データの量を制限せずに GET 要求$selectを行う場合、Microsoft Graph には、次のようなメッセージを使用$selectするためのベスト プラクティスの推奨事項を提供する @microsoft.graph.tips プロパティが含まれています。
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",
リソースの 1 つのプロパティのみを読み取る
プロパティ名をパス セグメントとして指定することで、 を使用 $selectせずに、リソースの 1 つのプロパティを取得できます。 このクエリでは、複数のプロパティを取得することはできませんが、1 つのプロパティのみが必要な場合に便利です。
次の例では、ユーザーの displayName を 取得します。
GET https://graph.microsoft.com/beta/users/8afc02cb-4d62-4dba-b536-9f6d73e9be26/displayName HTTP/1.1
Authorization : Bearer {access_token}
コレクション内リソースの特定のプロパティの読み取り
1 つのリソースの特定のプロパティを読み取ることに加え、類似の $select クエリ パラメーターをコレクションに適用し、それぞれに返される特定のプロパティだけを使用してコレクション内のすべてのリソースを戻すことができます。
たとえば、サインインしているユーザーのドライブにある項目の名前を問い合わせるには、次の HTTPS GET 要求を送信します。
GET https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name HTTP/1.1
Authorization : Bearer {access_token}
成功した場合の応答は、次の例に示すように、200 OK 状態コードと、共有ファイルの名前のみを含むペイロードを返します。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/drive/root/children(name,type)",
"value": [
{
"@odata.etag": "\"{896A8E4D-27BF-424B-A0DA-F073AE6570E2},2\"",
"name": "Shared with Everyone"
},
{
"@odata.etag": "\"{B39D5D2E-E968-491A-B0EB-D5D0431CB423},1\"",
"name": "Documents"
},
{
"@odata.etag": "\"{9B51EA38-3EE6-4DC1-96A6-230E325EF054},2\"",
"name": "newFile.txt"
}
]
}
リレーションシップ経由で 1 つのリソースから別のリソースへとスキャンする
マネージャーは、自分に報告する他のユーザーとの directReports 関係を保持します。 ユーザーの直属の部下の一覧を問い合わせるために、次の HTTPS GET 要求を使用して、リレーションシップ走査経由で指定されたターゲットに移動できます。
GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com/directReports HTTP/1.1
Authorization : Bearer {access_token}
成功した場合の応答は、200 OK 状態と、次に示すペイロードを返します。
HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 152
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects/$entity",
"@odata.type": "#microsoft.graph.user",
"id": "c37b074d-fe9d-4e68-83ad-b4401d3be174",
"department": "Sales & Marketing",
"displayName": "Bonnie Kearney",
...
}
同様に、リレーションシップをたどることで関連リソースに移動できます。 たとえば、ユーザー メッセージ関係を使用すると、Microsoft Entra ユーザーから一連の Outlook メール メッセージへのトラバーサルが可能になります。 次の例は、REST API 呼び出しでこれを行う方法を示しています。
GET https://graph.microsoft.com/v1.0/me/messages HTTP/1.1
Authorization : Bearer {access_token}
表示のように、成功した場合の応答は 200 OK 状態とペイロードを返します。
HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
odata-version: 4.0
content-length: 147
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/Messages",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$top=1&$skip=1",
"value": [
{
"@odata.etag": "W/\"FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej\"",
"id": "<id-value>",
"createdDateTime": "2015-11-14T00:24:42Z",
"lastModifiedDateTime": "2015-11-14T00:24:42Z",
"changeKey": "FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej",
"categories": [],
"receivedDateTime": "2015-11-14T00:24:42Z",
"sentDateTime": "2015-11-14T00:24:28Z",
"hasAttachments": false,
"subject": "Did you see last night's game?",
"body": {
"ContentType": "HTML",
"Content": "<content>"
},
"BodyPreview": "it was great!",
"Importance": "Normal",
...
}
]
}
メタデータを参照し、EntityType を検索し、その NavigationProperty のすべての EntityType を確認することにより、特定のリソースのすべてのリレーションシップを確認できます。
呼び出しのアクションと関数
Microsoft Graph は、単なる作成、読み取り、更新、削除 (CRUD) 操作ではない方法でリソースを操作するためのアクションと関数もサポートしています。 アクションまたは関数の引数を入力するために HTTPS POST 要求の形を取ることがよくあります。 たとえば、次のアクションはサインインしているユーザー (me) に電子メール メッセージを送信させます。
POST https://graph.microsoft.com/v1.0/me/sendMail HTTP/1.1
authorization: bearer {access_token}
content-type: application/json
content-length: 96
{
"message": {
"subject": "Meet for lunch?",
"body": {
"contentType": "Text",
"content": "The new cafeteria is open."
},
"toRecipients": [
{
"emailAddress": {
"address": "garthf@contoso.com"
}
}
],
"attachments": [
{
"@odata.type": "microsoft.graph.fileAttachment",
"name": "menu.txt",
"contentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
}
]
},
"saveToSentItems": "false"
}
メタデータで使用可能なすべての関数を確認できます。 関数またはアクションとして表示されます。
Microsoft Graph SDK を使用する
SDK のパワーと使いやすさが好きですか? REST API を常に使用して Microsoft Graph を呼び出すことができますが、多くの一般的なプラットフォーム用の SDK も提供しています。 使用可能な SDK を調べるには、「 コード サンプルと SDK」を参照してください。
関連コンテンツ
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示