Outlook リソースの不変識別子を取得する

  • [アーティクル]

Outlook アイテム (メッセージ、イベント、連絡先、タスク) には、ユーザーは気づいていないか、大きな不満を感じている可能性のある、興味深い動作があります。それは、ID の変更です。 これは頻繁に発生するものではなく、アイテムが移動された場合のみ発生します。ただし、後で使用するために ID をオフラインで格納するアプリの場合、これは深刻な問題になることがあります。 不変識別子 (ID) を使用すると、アプリケーションはアイテムの有効期間中に変更されない ID を取得できます。

注:

Microsoft Graph のすべての識別子など、不変識別子では大文字と小文字が区別されます。 ID を比較する場合は、この点に留意してください。

メカニズム

不変 ID は、Microsoft Graph のオプション機能です。 オプト インするには、アプリケーションから、API 要求に追加の HTTP ヘッダーを含めて送信する必要があります。

Prefer: IdType="ImmutableId"

このヘッダーは、それが含まれる要求にのみ適用されます。 常に不変 ID を使用したい場合は、このヘッダーをすべての API 要求に含める必要があります。

不変 ID の有効期間

アイテムの変更できない ID は、アイテムが同じメールボックスに留まる限り変更されません。 つまり、アイテムがメールボックス内の別のフォルダーに移動しても、不変 ID は変更されません。 ただし、変更できない ID は、次の場合に変更されます。

  • ユーザーがアイテムをアーカイブ メールボックスに移動する。
  • ユーザーがアイテムをエクスポートし (PST へのエクスポート、MSG ファイルとしてのエクスポートなど)、それをメールボックスに再度インポートする。

不変 ID をサポートするアイテム

不変 ID をサポートするアイテムは次のとおりです。

コンテナーの種類 (mailFolder、予定表など) は変更できない ID をサポートしていませんが、通常の ID は既に一定でした。

メール送信時の不変 ID

次の手順で、不変 ID を使用すると、メール送信後に送信済みアイテムフォルダー内のメッセージを検索ができます。

  1. Prefer: IdType="ImmutableId" ヘッダーを使用して、メッセージの下書き を作成し、メッセージの id プロパティを応答に保存します。
  2. 前の手順の ID を使用して メッセージを送信します。
  3. ID を使用して メッセージを取得します。 これは送信済みアイテムのコピーです。

注:

メッセージの送信直後は、送信済みアイテム内のメッセージを取得できないことがあります。 メッセージのコピーは、メッセージの送信が成功するまで作成されません。そのため、時間がかかる場合があります。

変更通知を使用する不変 ID

サブスクリプションの作成時に Prefer: IdType="ImmutableId"ヘッダーを含めることで、Microsoft Graph が変更通知で不変 ID を送信するように要求することができます。 ヘッダーなしで作成された既存のサブスクリプションでは、引き続き既定の ID 形式が使用されます。 既存のサブスクリプションを、不変 ID を使用するように切り替えるには、そのサブスクリプションを削除し、このヘッダーを使用して作成し直す必要があります。

デルタ クエリを使用する不変 ID

Prefer: IdType="ImmutableId" ヘッダーを含めることで、Microsoft Graph が不変 ID を、サポートされるリソース型に関するデルタ クエリ応答で返すように要求することができます。 @odata.nextLinkデルタ クエリによって返される と @odata.deltaLink の値は両方の ID 形式と互換性があるため、変更できない ID を利用するためにアプリケーションを再同期する必要はありません。 今後は、このヘッダーを使用して不変 ID を取得でき、アプリの記憶域を個別に更新することができます。

既存のデータの更新

データベースが既に何千個もの標準 ID でいっぱいになっている場合、translateExchangeIds 関数を使用して、それらの ID を不変形式に移行することができます。 最大 1000 個もの ID をターゲット形式に変換できます。

注:

translateExchangeIds を使用して、Exchange Web サービス アプリケーションを Microsoft Graph に移行することもできます。

例

次の例では、通常のMicrosoft Graph ID を変更できないMicrosoft Graph ID に変換します。

要求

POST https://graph.microsoft.com/v1.0/me/translateExchangeIds

{
  "inputIds" :
  [
    "AQMkAGM2…"
  ],
  "targetIdType" : "restImmutableEntryId",
  "sourceIdType" : "restId"
}

応答

HTTP 200 OK

{
  "value": [
    {
      "targetId": "AAkALgAA...",
      "sourceId": "AQMkAGM2..."
    }
  ]
}