トレーニング
モジュール
Microsoft Graph を使用して JavaScript アプリでユーザーのメールを表示する - Training
Microsoft Graph を使用して JavaScript アプリでユーザーのメールを表示する方法を説明します。 また、Microsoft Graph クエリの最適化と大規模なデータ セットのページングの方法も説明します。
このブラウザーはサポートされなくなりました。
Microsoft Edge にアップグレードすると、最新の機能、セキュリティ更新プログラム、およびテクニカル サポートを利用できます。
デルタ クエリでは、一連の デルタ 関数呼び出しを使用して、フォルダー内のメッセージへの追加、削除、または更新に対してクエリを実行できます。 デルタ データを使用すると、毎回サーバーからユーザーのメッセージのセット全体をフェッチせずに、ユーザーのメッセージのローカル ストアの保守と同期が行えます。
ローカル ストア内のメッセージ項目を同期すると、最初の完全同期とその後の増分同期に デルタ クエリを使用できます。 通常、フォルダー内のすべてのメッセージ (ユーザーの受信トレイなど) の初期完全同期を行い、そのフォルダーに対する増分変更を定期的に取得します。
最初の同期以降に作成、更新、または削除された特定の種類のメッセージのみの増分変更を取得するには、フォルダー内のすべてのメッセージの初期同期を行い、後続のラウンドで特定の目的の種類の増分変更を取得します。 最初のデルタ要求でクエリ オプションとして目的の変更の種類を指定します。Microsoft Graph は、OData およびカスタム クエリ オプションを 応答で 指定された @odata.deltaLink に@odata.nextLink自動的にエンコードします。
デルタ クエリはフォルダー単位の操作です。 フォルダー階層内のメッセージの変更を追跡するには、各フォルダーを個別に追跡する必要があります。
通常、メール フォルダー内のメッセージ変更の追跡は、デルタ関数を使用した、1 つ以上の GET 要求のラウンドです。 最初の GET 要求は、デルタ関数を含めることを除いて、メッセージの取得方法とほぼ同じです。
GET https://graph.microsoft.com/v1.0/me/mailFolders/{id}/messages/delta
デルタ関数を使用した GET 要求は、次のいずれかを返します。
@odata.nextLink
(デルタ関数の呼び出しと skipToken を使用した URL を含む)、または@odata.deltaLink
(デルタ関数の呼び出しと deltaToken を使用した URL を含む)。これらのトークンは、クライアントに対して不透明な 状態トークン です。
変更追跡のラウンドを続行するには、最後の GET 要求から返された URL をコピーして、同じフォルダーの次の デルタ 関数呼び出しに適用します。 応答で返される @odata.deltaLink
は、変更追跡の現在のラウンドが完了したことを示します。
@odata.deltaLink
URL を保存して、次のラウンドを開始する際に使用することができます。
この記事の残りの部分には、次の 2 つの例が含まれています。
@odata.deltaLink
URL の使用方法@odata.nextLink
については、例 1 を参照してください。$select
使用して、最適なパフォーマンスを得るために必要なプロパティのみを指定できます。 プロパティは id
常に返されます。$select
、$top
、および $expand
をサポートします。$filter
と $orderby
に対するサポートには制限があります。$filter
式は、$filter=receivedDateTime+ge+{value}
または $filter=receivedDateTime+gt+{value}
です。$filter
を適用すると、最大 5,000 件のメッセージが返されます。$orderby
式は、$orderby=receivedDateTime+desc
です。 式を $orderby
含めない場合、戻り値の順序は保証されません。$search
に対するサポートはありません。さらに、デルタ クエリの応答で特定の種類の変更 (作成、更新、または削除) のみを返すには、必要に応じて、カスタム クエリ オプション changeType
を使用して目的の種類の変更をフィルター処理できます。 指定できる値は、 created
、 updated
または deleted
です。
GET /me/mailfolders/{id}/messages/delta?changeType=created
GET /me/mailfolders/{id}/messages/delta?changeType=updated
GET /me/mailfolders/{id}/messages/delta?changeType=deleted
各デルタ クエリの GET 要求は、応答で 1 つ以上のメッセージのコレクションを返します。 必要に応じて、要求ヘッダー Prefer: odata.maxpagesize={x}
を指定して、応答内の最大メッセージ数を設定できます。
次の例では、初めに 5 件のメッセージを含む特定のフォルダーを 2 回同期しています。
最初のラウンドには、フォルダー内の 5 つのメッセージをすべて同期するための一連の 3 つの要求が含まれます。
最初のラウンドの後、メッセージの 1 つが削除され、別の 1 つのメッセージが既読としてマークされます。 同期の 2 回目のラウンドでは、変更されていない他のメッセージは返さず、デルタ (削除と更新) のみを返します。
この例では、指定したフォルダーが初めて同期されるため、初期同期要求には状態トークンは含まれません。 このラウンドは、そのフォルダー内のすべてのメッセージを返します。
最初の要求では、次のものを指定しています。
subject
プロパティ、sender
プロパティ、isRead
プロパティを返す $select
パラメーター。GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2
応答には、2 つのメッセージと応答ヘッダーが @odata.nextLink
含まれます。
URL は、取得するフォルダーにさらにメッセージがあることを示します。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
"subject": "Holiday hours update",
"isRead": false,
"sender": {
"emailAddress": {
"name": "Dana Swope",
"address": "danas@contoso.com"
}
},
"id": "AAMkADNkNAAASq35xAAA="
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB/\"",
"subject": "Holiday promotion sale",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
},
"id": "AQMkADNkNAAAVRMKAAAAA=="
}
]
}
2 番目の要求では、前の応答で返された @odata.nextLink
URL が指定されます。 URL 内の と同じパラメーターがエンコードされて含まれるのskipToken
で、最初の要求と同じ$select
パラメーターを@odata.nextLink
指定する必要がなくなりました。
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPuoTQWfcsAbkYM HTTP/1.1
Prefer: odata.maxpagesize=2
2 番目の応答は、フォルダーから取得するメッセージがまだあることを示す、フォルダー内の次の 2 つのメッセージと別の @odata.nextLink
を返します。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlqfdAAAEfYB+\"",
"subject": "Microsoft Virtual Academy at Contoso",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Elliot Hyde",
"address": "elliot-hyde@tailspintoys.com"
}
},
"id": "AQMkADNkNAAAgWkAAAA"
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAAEfYB+\"",
"subject": "New or modified user account information",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Randi Welch",
"address": "randiw@contoso.com"
}
},
"id": "AQMkADNkNAAAgWJAAAA"
}
]
}
3 番目の要求は、最後の同期要求から返された最新の @odata.nextLink
URL を引き続き使用します。
GET https://graph.microsoft.com/v1.0/me/mailFolders/AQMkADNkNAAAgEMAAAA/messages/delta?$skiptoken=GwcBoTmPKILK4jLH7mAd1lLU HTTP/1.1
Prefer: odata.maxpagesize=2
3 番目の応答は、フォルダー内の残りの唯一のメッセージと @odata.deltaLink
、このフォルダーの同期が完了したことを示す URL を返します。 URL を @odata.deltaLink
保存して使用して 、次のラウンドで同じフォルダーを同期します。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzFPjSbaPPxzjlzOTAAAEfYB+\"",
"subject": "Fabric CDN now available",
"isRead": true,
"sender": {
"emailAddress": {
"name": "Jodie Sharp",
"address": "Jodie.Sharp@contoso.com"
}
},
"id": "AAMkADk0MGFkODE3LWEAAA="
}
]
}
@odata.deltaLink
最後のラウンドの最後の要求から を使用すると、そのフォルダー内で変更 (追加、削除、または更新) されたメッセージのみを取得できます。
次のラウンドの最初の要求は、同じ最大ページ サイズを維持することを前提とすると、次のようになります。
GET https://graph.microsoft.com/v1.0/me/mailfolders/AQMkADNkNAAAgEMAAAA/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY HTTP/1.1
Prefer: odata.maxpagesize=2
応答には @odata.deltaLink
が含まれます。 これは、リモート メール フォルダー内のすべての変更が同期されていることを示します。 1 つのメッセージは削除され、その他のメッセージは変更されました。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailfolders('AQMkADNkNAAAgEMAAAA')/messages/delta?$deltatoken=GwcBoTmPuoGNlgXgF1nyUNMXY",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS0Dh_6qB-pB2Sa2pUum19a6YAAKnLuxoAAA=",
"@removed": {
"reason": "deleted"
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAAARn2vdzPFjSbaPPxzjlzOTAAASsKZz\"",
"subject": "Holiday hours update",
"isRead": "true",
"sender": {
"emailAddress": {
"name": "Dana Swope",
"address": "danas@contoso.com"
}
},
"id": "AAMkADNkNAAASq35xAAA="
}
]
}
次の例は、最初の同期以降に特定のフォルダーに作成されたメッセージのみを取得する方法を示しています。この例では、最初に 4 つのメッセージを含むフォルダーの同期を 2 回行います。
最初のラウンドでは、フォルダー内のすべての 4 つのメッセージを同期するための一連の 2 つの要求が含まれます。
最初のラウンドの後、さらに 2 つのメッセージが作成され、1 つのメッセージが削除され、もう 1 つのメッセージが読み取りとしてマークされます。
2 回目の同期では、変更の種類 (作成された 2 つの新しいメッセージ) のフォルダー内の created
変更のみが返されます。最後の同期以降も同じ、削除、または更新された他のメッセージは返されません。
この例では、指定したフォルダーが初めて同期されるため、初期同期要求には状態トークンは含まれません。 このラウンドは、そのフォルダー内のすべてのメッセージを返します。
最初の要求では、次のものを指定しています。
changeType
デルタ応答で 作成 されたメッセージのみを返すパラメーター。subject
プロパティ、sender
プロパティ、isRead
プロパティを返す $select
パラメーター。GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?changeType=created&$select=subject,sender,isRead HTTP/1.1
Prefer: odata.maxpagesize=2
応答には、2 つのメッセージと応答ヘッダーが @odata.nextLink
含まれます。
URL は、取得するフォルダーにさらにメッセージがあることを示します。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBP\"",
"subject": "Inline Attachments Again",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LT2fKdhq8oSKEDSVrdi3lRAAIei5gdAAA=",
"sender": {
"emailAddress": {
"name": "Megan Brown",
"address": "Megan.Brown@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBR\"",
"subject": "RE: Test Outlook TimeZone",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMKdhq8oSKEDSVrdi3lRAAIei5geAAA=",
"sender": {
"emailAddress": {
"name": "Megan Brown",
"address": "Megan.Brown@contoso.com"
}
}
}
]
}
2 番目の要求では、前の応答で返された @odata.nextLink
URL が指定されます。 URL 内の がエンコードして含めるので、skipToken
最初の要求と同じ$select
またはchangeType
パラメーターを@odata.nextLink
指定する必要がなくなったことに注意してください。
GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=P4lmXpjPRrjB6haAQzSkpK89jYTVD2kVtOeXNRnfYzPbCs HTTP/1.1
Prefer: odata.maxpagesize=2
2 番目の応答は、フォルダー内の次の 2 つのメッセージと、 @odata.deltaLink
このフォルダーの同期が完了したことを示す URL を返します。 URL を @odata.deltaLink
保存して使用して 、次のラウンドで同じフォルダーを同期します。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBu\"",
"subject": "Your preview of the new Briefing email",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
"sender": {
"emailAddress": {
"name": "Cortana",
"address": "cortana@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MBw\"",
"subject": "Char Coding HTML",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBA=",
"sender": {
"emailAddress": {
"name": "John Doe",
"address": "John.Doe@contoso.com"
}
}
}
]
}
@odata.deltaLink
最後のラウンドの最後の応答から を使用すると、そのフォルダーに追加されたメッセージのみを取得できます。
次のラウンドの最初の要求は、同じ最大ページ サイズを維持することを前提とすると、次のようになります。
GET https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$deltatoken=P4lmXpjPRrjB6haAQ_37roqIbjXe66KoV7SMlLH--Jgi8 HTTP/1.1
Prefer: odata.maxpagesize=2
応答には @odata.deltaLink
が含まれます。 これは、リモート メール フォルダー内のすべての変更が同期されていることを示します。 前回の同期以降に 2 つのメッセージが追加されました。最後の同期以降に更新 & 削除されたメッセージは、この差分応答では返されません。
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(message)",
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/mailFolders/AAMkAGUwNc4LTMzAAA=/messages/delta?$skiptoken=EPuhZPRDHo-r3EBfscYE444fuGSBRV1eXex3JZkLzT9fRM",
"value": [
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCP\"",
"subject": "Nested Attachment",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwBIJ",
"sender": {
"emailAddress": {
"name": "Patti Fernandez",
"address": "PattiF@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.message",
"@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAId0MCN\"",
"subject": "Attachment Testing",
"isRead": true,
"id": "AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMzNjMwNWM0ZGE2YQBGAAAAAADbrwZA=",
"sender": {
"emailAddress": {
"name": "Patti Fernandez",
"address": "PattiF@contoso.com"
}
}
}
]
}
トレーニング
モジュール
Microsoft Graph を使用して JavaScript アプリでユーザーのメールを表示する - Training
Microsoft Graph を使用して JavaScript アプリでユーザーのメールを表示する方法を説明します。 また、Microsoft Graph クエリの最適化と大規模なデータ セットのページングの方法も説明します。