英語で読む

次の方法で共有


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..."
    }
  ]
}