Microsoft Graph 内を移動してデータとメソッドにアクセスする

Microsoft Graph API を使用してデータの読み取りと書き込みを行うだけでなく、多数の要求パターンを使用して Microsoft Graph のリソースをスキャンすることができます。また、メタデータ ドキュメントによって、リソースのデータ モデル、および Microsoft Graph 内のリレーションシップを理解することができます。

Microsoft Graph API メタデータ

メタデータ ドキュメント ($metadata) が、サービス ルートに公開されます。Microsoft Graph API の v1.0 およびベータ版のサービス ドキュメントは、次の URL で表示できます。

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 で定義されます。

メタデータを使用して、Microsoft Graph のエンティティ間のリレーションシップを学ぶことができ、また、それらのエンティティ間を移動する URL を作成することができます。

注意

  • リソース ID の大文字と小文字の区別 は、Microsoft Graph API から返されたものと同じものを使用します。
  • リソース ID、ユーザーが割り当てる値、およびその他の base-64 でエンコードされた値は、大文字と小文字が区別される ものと考えてください。
  • パス URL リソース名、クエリパラメーター、アクション名、関数名、API プロパティ名と値を含むそれらのリクエスト本文パラメーターは、大文字と小文字を区別しない ものと考えてください。

リソースのコレクションを表示する

Microsoft Graph では、HTTP GET クエリを使用してテナント内のリソースを表示することができます。クエリの応答には、各リソースのプロパティが含まれます。各エンティティ リソースは、その ID によって識別されます。リソース ID の形式は GUID にすることができ、一般的にはリソースの種類によって異なります。

たとえば、テナント内で定義されている user リソースのコレクションを取得できます。

GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization : Bearer {access_token}

成功した場合は、200 OK 応答が返され、そのペイロードに user リソースのコレクションが含まれています。各ユーザーは 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.onmicrosoft.com",
      "mobilePhone":"+1 3528700812",
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Administrator",
      "userPrincipalName":"admin@contoso.onmicrosoft.com"
    },
    {
      "id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
      "businessPhones":[

      ],
      "displayName":"Alan Steiner",
      "givenName":"Alan",
      "jobTitle":"VP Corporate Marketing",
      "mail":"alans@contoso.onmicrosoft.com",
      "mobilePhone":null,
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Steiner",
      "userPrincipalName":"alans@contoso.onmicrosoft.com"
    }
  ]
}

Microsoft Graph を使用すると、1 つのリソースと別のリソース間のリレーションシップをナビゲートすることにより、コレクションを表示することもできます。たとえば、ユーザーの mailFolders ナビゲーション プロパティを通して、そのユーザーのメールボックス内の mailFolder リソースのコレクションに対してクエリを実行することができます。

GET https://graph.microsoft.com/v1.0/me/mailfolders HTTP/1.1
Authorization : Bearer {access_token}

成功した場合は、200 OK 応答が返され、そのペイロードに mailFolder リソースのコレクションが含まれています。各 mailFolderid プロパティによって識別され、いくつかのプロパティも返されます。簡潔にするため、以下に示すペイロードは切り捨てられています。

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 ごとにコレクションから特定のリソースを表示する

引き続き、例として user を使用します。ユーザーに関する情報を表示するには、HTTPS GET 要求を使用してユーザーの ID から特定のユーザーを取得します。user エンティティでは、id または userPrincipalName プロパティのいずれかを識別子として使用できます。

次の要求の例では、ユーザーの ID として userPrincipalName の値を使用しています。

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.onmicrosoft.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.onmicrosoft.com",

    ...
}

リソースの特定のプロパティの読み取り

ユーザーから提供された 自己紹介 の記述やスキル セットなどのユーザーの個人データのみを取得するには、次の例に示したように、以前の要求に $select クエリ パラメーターを追加することができます。

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.onmicrosoft.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 エンティティのプロパティ セット全体ではなく、aboutMedisplayNameskills という基本的なプロパティのみが返されます。

コレクション内リソースの特定のプロパティの読み取り

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.onmicrosoft.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.onmicrosoft.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",

    ...
}

同様に、リレーションシップをたどると、関連リソースに移動できます。たとえば、ユーザーとメッセージ間のリレーションシップにより、Azure Active Directory (Azure AD) ユーザーから 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.onmicrosoft.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.onmicrosoft.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」を参照してください。

関連項目