Outlook リソースの不変 ID の取得Get immutable identifiers for Outlook resources

Outlook アイテム (メッセージ、イベント、連絡先、タスク) には、ユーザーは気づいていないか、大きな不満を感じている可能性のある、興味深い動作があります。それは、ID の変更です。Outlook items (messages, events, contacts, tasks) have an interesting behavior that you've probably either never noticed or has caused you significant frustration: their IDs change. これは頻繁に発生するものではなく、アイテムが移動された場合のみ発生します。ただし、後で使用するために ID をオフラインで格納するアプリの場合、これは深刻な問題になることがあります。It doesn't happen often, only if the item is moved, but it can cause real problems for apps that store IDs offline for later use. 不変 ID を使用すると、お使いのアプリケーションで、アイテムの有効期間中は変更のない ID を取得できます。Immutable identifiers enables your application to obtain an ID that does not change for the lifetime of the item.

重要: 不変 ID は、Microsoft Graph のベータ版のみで使用できます。Important: Immutable identifiers are only available on the /beta version in Microsoft Graph.

メカニズムHow it works

不変 ID は、Microsoft Graph のオプション機能です。Immutable ID is an optional feature for Microsoft Graph. オプト インするには、アプリケーションから、API 要求に追加の HTTP ヘッダーを含めて送信する必要があります。To opt in, your application needs to send an additional HTTP header in your API requests:

Prefer: IdType="ImmutableId"

このヘッダーは、それが含まれる要求にのみ適用されます。This header only applies to the request it is included with. 常に不変 ID を使用したい場合は、このヘッダーをすべての API 要求に含める必要があります。If you want to always use immutable IDs, you must include this header with every API request.

不変 ID の有効期間Lifetime of Immutable IDs

アイテムの不変 ID は、アイテムが同じメールボックス内にある限り、変更されません。An item's immutable ID will not change so long as the item stays in the same mailbox. つまり、アイテムがメールボックス内の別のフォルダーに移動しても、不変 ID は変更されません。That means that immutable ID will NOT change if the item is moved to a different folder in the mailbox. ただし、次の場合、不変 ID は変更されます。However, the immutable ID will change if:

  • ユーザーがアイテムをアーカイブ メールボックスに移動したThe user moves the item to an archive mailbox
  • ユーザーがアイテムをエクスポートし (PST へのエクスポート、MSG ファイルとしてのエクスポートなど)、それをメールボックスに再度インポートしたThe user exports the item (to a PST, as an MSG file, etc.) and re-imports it into their mailbox

不変 ID をサポートするアイテムItems that support immutable ID

不変 ID をサポートするアイテムは次のとおりです。The following items support immutable IDs:

コンテナー型 (mailFolder、calendar など) は不変 ID をサポートしませんが、コンテナー型の標準 ID は既に不変です。Container types (mailFolder, calendar, etc.) do not support immutable ID, but their regular IDs were already constant.

変更通知を使用する不変 IDImmutable ID with change notifications

サブスクリプションの作成時に Prefer: IdType="ImmutableId"ヘッダーを含めることで、Microsoft Graph が変更通知で不変 ID を送信するように要求することができます。You can request that Microsoft Graph send immutable IDs in change notifications by including the Prefer: IdType="ImmutableId" header when creating a subscription. このヘッダーなしで作成された既存のサブスクリプションは、既定の ID 形式を使用し続けます。Existing subscriptions created without the header will continue to use the default ID format. 既存のサブスクリプションを、不変 ID を使用するように切り替えるには、そのサブスクリプションを削除し、このヘッダーを使用して作成し直す必要があります。In order to switch existing subscriptions to use immutable IDs, you must delete and recreate them using the header.

デルタ クエリを使用する不変 IDImmutable ID with delta query

Prefer: IdType="ImmutableId" ヘッダーを含めることで、Microsoft Graph が不変 ID を、サポートされるリソース型に関するデルタ クエリ応答で返すように要求することができます。You can request that Microsoft Graph return immutable IDs in delta query responses for supported resource types by including the Prefer: IdType="ImmutableId" header. デルタ クエリによって返される nextLinkdeltaLink の各値は、両方の ID 形式に対応しているので、アプリケーションは、不変 ID を利用するために再同期する必要はありません。The nextLink and deltaLink values returned by delta queries are compatible with both ID formats, so your application does not need to re-synchronize to take advantage of immutable ID. 今後は、このヘッダーを使用して不変 ID を取得でき、アプリの記憶域を個別に更新することができます。You can use the header to get immutable IDs going forward, and you can update your app's storage separately.

既存のデータの更新Updating existing data

データベースが既に何千個もの標準 ID でいっぱいになっている場合、translateExchangeIds 関数を使用して、それらの ID を不変形式に移行することができます。If you've already got a database filled with thousands of regular IDs, you can migrate those IDs to immutable format using the translateExchangeIds function. 最大 1000 個もの ID をターゲット形式に変換できます。You can provide an array of up to 1000 IDs to be translated into a target format.

注: translateExchangeIds を使用して、Exchange Web サービス アプリケーションを Microsoft Graph に移行することもできます。Note: You can also use translateExchangeIds to migrate Exchange Web Services applications to Microsoft Graph.

Example

次の例では、標準の Graph ID を不変の Graph ID に変換します。The following example translates a normal Graph ID to an immutable Graph ID.

要求Request

POST https://graph.microsoft.com/beta/me/translateExchangeIds

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

応答Response

HTTP 200 OK

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