Erhalten Sie unveränderliche Bezeichner für Outlook-Ressourcen

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. 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. Mit unveränderlichen Bezeichnern (IDs) kann Ihre Anwendung eine ID abrufen, die sich für die Lebensdauer des Elements nicht ändert.

Funktionsweise

Unveränderliche IDs stellen ein optionales Feature von Microsoft Graph dar. Um sich dafür zu entscheiden, muss Ihre Anwendung einen zusätzlichen HTTP-Header in Ihren API-Anforderungen senden:

Prefer: IdType="ImmutableId"

Dieser Header gilt nur für die Anforderung, in der er enthalten ist. Wenn Sie immer unveränderliche IDs verwenden möchten, müssen Sie diesen Header in jede API-Anforderung aufnehmen.

Lebensdauer von unveränderlichen IDs

Die unveränderliche ID eines Elements ändert sich nicht, solange das Element im selben Postfach verbleibt. Das bedeutet, dass sich die unveränderliche ID NICHT ändert, wenn das Element in einen anderen Ordner im Postfach verschoben wird. Die unveränderliche ID ändert sich jedoch, wenn:

• Der Benutzer verschiebt das Element in ein Archivpostfach.
• Der Benutzer exportiert das Element (in eine PST-Datei, als MSG-Datei usw.) und importiert es anschließend wieder in sein Postfach.

Elemente, die unveränderliche IDs unterstützen

Die folgenden Elemente unterstützen unveränderliche IDs:

• Ressourcentyp Nachricht
• Ressourcentyp Anlage
• Ressourcentyp Ereignis
• Ressourcentyp eventMessage
• Ressourcentyp Kontakt
• Ressourcentyp outlookTask

Containertypen (mailFolder, Kalender usw.) unterstützen keine unveränderliche ID, aber ihre regulären IDs waren bereits konstant.

Unveränderliche ID mit dem Senden von E-Mails

Mithilfe der folgenden Schritte können Sie unveränderliche IDs für die Suche nach einer Nachricht im Ordner „Gesendete Elemente“ verwenden, nachdem diese Nachricht gesendet wurde:

1. Erstellen Sie einen Nachrichtenentwurf. Verwenden Sie die Prefer: IdType="ImmutableId"-Kopfzeile, und speichern Sie die id-Eigenschaft der Nachricht in der Antwort.
2. Senden Sie die Nachricht mithilfe der ID aus dem vorherigen Schritt ab.
3. Erhalten Sie die Nachricht mithilfe der ID aus dem ersten Schritt. Dies ist die Kopie in „Gesendete Elemente“.

Unveränderliche IDs mit Änderungsbenachrichtigungen

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. Vorhandene Abonnements, die ohne den -Header erstellt wurden, verwenden weiterhin das Standard-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.

Unveränderliche IDs mit Delta-Abfragen

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. Die @odata.nextLink von Delta-Abfragen zurückgegebenen Werte und @odata.deltaLink sind mit beiden ID-Formaten kompatibel, sodass Ihre Anwendung nicht erneut synchronisiert werden muss, um die Vorteile der unveränderlichen ID zu nutzen. Sie können den Header verwenden, um von jetzt an unveränderliche IDs abzurufen, und Sie können den Speicher Ihrer App separat aktualisieren.

Aktualisieren vorhandener Daten

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. Sie können ein Array von bis zu 1.000 IDs angeben, die in ein Zielformat übersetzt werden sollen.

Beispiel

Im folgenden Beispiel wird eine normale Microsoft Graph ID in eine unveränderliche Microsoft Graph ID übersetzt.

Anforderung

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

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

Antwort

HTTP 200 OK

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