Abrufen von unveränderlichen Bezeichnern für Outlook-RessourcenGet immutable identifiers for Outlook resources

Outlook-Elemente (Nachrichten, Ereignisse, Kontakte, Aufgaben) haben ein interessantes Verhalten, das Sie vermutlich entweder noch nie bemerkt haben oder das bei Ihnen erhebliche Frustration ausgelöst hat: ihre IDs ändern sich.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. Das geschieht nicht oft, nur wenn das Element verschoben wird, es kann aber für Apps, die IDs zwecks späterer Verwendung offline speichern, zu echten Problemen führen.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. Unveränderliche Bezeichner ermöglichen Ihrer Anwendung das Abrufen einer ID, die sich über die gesamte Lebensdauer des Elements nicht ändert.Immutable identifiers enables your application to obtain an ID that does not change for the lifetime of the item.

Wichtig: Unveränderliche Bezeichner sind nur in der /beta-Version von Microsoft Graph verfügbar.Important: Immutable identifiers are only available on the /beta version in Microsoft Graph.

FunktionsweiseHow it works

Unveränderliche IDs stellen ein optionales Feature von Microsoft Graph dar.Immutable ID is an optional feature for Microsoft Graph. Um sich dafür zu entscheiden, muss Ihre Anwendung einen zusätzlichen HTTP-Header in Ihren API-Anforderungen senden:To opt in, your application needs to send an additional HTTP header in your API requests:

Prefer: IdType="ImmutableId"

Dieser Header gilt nur für die Anforderung, in der er enthalten ist.This header only applies to the request it is included with. Wenn Sie immer unveränderliche IDs verwenden möchten, müssen Sie diesen Header in jede API-Anforderung aufnehmen.If you want to always use immutable IDs, you must include this header with every API request.

Lebensdauer unveränderlicher IDsLifetime of Immutable IDs

Die unveränderliche ID eines Elements ändert sich nicht, solange das Element im gleichen Postfach verbleibt.An item's immutable ID will not change so long as the item stays in the same mailbox. Das bedeutet, dass sich die unveränderliche ID NICHT ändert, wenn das Element in einen anderen Ordner im Postfach verschoben wird.That means that immutable ID will NOT change if the item is moved to a different folder in the mailbox. Die unveränderliche ID ändert sich aber unter diesen Umständen:However, the immutable ID will change if:

  • Der Benutzer verschiebt das Element in ein ArchivpostfachThe user moves the item to an archive mailbox
  • Der Benutzer exportiert das Element (in eine PST-Datei, als MSG-Datei usw.) und importiert es anschließend wieder in sein PostfachThe user exports the item (to a PST, as an MSG file, etc.) and re-imports it into their mailbox

Elemente, die unveränderliche IDs unterstützen.Items that support immutable ID

Die folgenden Elemente unterstützen unveränderliche IDs:The following items support immutable IDs:

Containertypen (mailFolder, calendar usw.) unterstützen keine unveränderlichen IDs, aber ihre regulären IDs stellen bereits Konstanten dar.Container types (mailFolder, calendar, etc.) do not support immutable ID, but their regular IDs were already constant.

Unveränderliche IDs mit ÄnderungsbenachrichtigungenImmutable ID with change notifications

Sie können festlegen, dass Microsoft Graph unveränderliche IDs in Änderungsbenachrichtigungen sendet, indem Sie den Header Prefer: IdType="ImmutableId" beim Erstellen eines Abonnements einschließen.You can request that Microsoft Graph send immutable IDs in change notifications by including the Prefer: IdType="ImmutableId" header when creating a subscription. Vorhandene Abonnements, die ohne den Header erstellt wurden, verwenden weiterhin das ID-Standardformat.Existing subscriptions created without the header will continue to use the default ID format. Um vorhandene IDs auf die Verwendung von unveränderlichen IDs umzustellen, müssen Sie sie löschen und unter Verwendung des Headers neu erstellen.In order to switch existing subscriptions to use immutable IDs, you must delete and recreate them using the header.

Unveränderliche IDs mit Delta-AbfragenImmutable ID with delta query

Sie können festlegen, dass Microsoft Graph für unterstützte Ressourcentypen unveränderliche IDs in Antworten auf Delta-Abfragen zurückgibt, indem Sie den Header Prefer: IdType="ImmutableId" einschließen.You can request that Microsoft Graph return immutable IDs in delta query responses for supported resource types by including the Prefer: IdType="ImmutableId" header. Die von Delta-Abfragen zurückgegebenen Werte nextLink und deltaLink sind mit beiden ID-Formaten kompatibel, daher muss Ihre Anwendung nicht neu synchronisiert werden, um unveränderliche IDs zu nutzen.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. Sie können den Header verwenden, um von jetzt an unveränderliche IDs abzurufen, und Sie können den Speicher Ihrer App separat aktualisieren.You can use the header to get immutable IDs going forward, and you can update your app's storage separately.

Aktualisieren vorhandener DatenUpdating existing data

Wenn Sie bereits über eine Datenbank verfügen, die mit Tausenden regulärer IDs gefüllt ist, können Sie diese IDs mithilfe der Funktion translateExchangeIds in das unveränderliche Format konvertieren.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. Sie können ein Array von bis zu 1.000 IDs angeben, die in ein Zielformat übersetzt werden sollen.You can provide an array of up to 1000 IDs to be translated into a target format.

Hinweis: translateExchangeIds kann auch für die Migration von Exchange-Webdiensten nach Microsoft Graph verwendet werden.Note: You can also use translateExchangeIds to migrate Exchange Web Services applications to Microsoft Graph.

BeispielExample

Im folgenden Beispiel wird eine normale Graph-ID in eine unveränderliche Graph-ID übersetzt.The following example translates a normal Graph ID to an immutable Graph ID.

AnforderungRequest

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

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

AntwortResponse

HTTP 200 OK

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