Erste Schritte mit der Exchange Online Admin-API

Hinweis

Die in diesem Artikel beschriebenen Features befinden sich derzeit in der Vorschauphase, sind nicht in allen Organisationen verfügbar und können sich ändern.

In diesem Artikel erfahren Sie, wie Sie Ihren ersten erfolgreichen Exchange Online Admin API-Aufruf durchführen, und erläutert die wichtigsten Verhaltensweisen und Muster, die für alle Endpunkte gelten.

Dieser Artikel hilft Ihnen bei den folgenden Aufgaben:

Hier erfahren Sie, wie Sie eine Anforderung (Header und Text) zum Aufrufen der Exchange Online Admin-API erstellen.
Unterstützte Umgebungen und Basis-URLs, die für jede Umgebung verwendet werden sollen.
Funktionsweise der Paginierung und Eigenschaftenauswahl.
Wann und wie X-AnchorMailbox für das Routing verwendet wird.
Häufige Probleme und bewährte Methoden.

Die Exchange Online Admin-API bietet eine REST-basierte Möglichkeit zum Ausführen bestimmter PowerShell-Cmdlets, die legacy-Szenarien für Exchange-Webdienste (EWS) ersetzen. Weitere Informationen finden Sie unter Übersicht über die Exchange Online Admin-API.

Voraussetzung: Einrichten von Authentifizierung und Berechtigungen

Bevor Sie die Exchange Online Admin-API zum ersten Mal aufrufen können, müssen Sie Authentifizierung und Berechtigungen einrichten, damit Ihre App oder Ihr Skript sicher auf Ihre organization zugreifen kann. Vollständige Anweisungen finden Sie unter Authentifizierung und Autorisierung für die Exchange Online Admin-API.

Hier sind die zusammengefassten Schritte:

Registrieren einer App in Microsoft Entra ID: Erstellen Sie eine App-Registrierung für delegierten oder nur App-Zugriff.
Api-Berechtigungen erteilen:
- Delegiert: Exchange.ManageV2.
- Nur App: Exchange.ManageAsAppV2.
Administratoreinwilligung einholen: Stellen Sie sicher, dass den Berechtigungen auf organization Ebene zugestimmt wird.
Zuweisen von RBAC-Rollen: Weisen Sie dem Benutzer (delegiert) oder Dienstprinzipal (nur App) Rollen zu, die die von Ihnen verwalteten Objekte abdecken.
Abrufen eines Zugriffstokens: Verwenden Sie delegierte oder nur App-Flows, um ein gültiges OAuth-Token abzurufen.
Kennen Sie Ihren organization Kontext: Identifizieren Sie Ihre Mandanten-ID (GUID) und Die Basis-URL.

Unterstützte Umgebungen und Basis-URLs

Die Exchange Online Admin-API ist in allen Exchange Online-Umgebungen verfügbar. Jede Umgebung verwendet eine andere Basis-URL für Anforderungen. Stellen Sie daher sicher, dass Sie die richtige URL für Ihre Umgebung verwenden, wie in der folgenden Tabelle beschrieben:

Umgebung	Basis-URL
Microsoft 365 oder Microsoft 365 GCC	`https://outlook.office365.com`
Office 365 betrieben von 21Vianet (China)	`https://outlook.office365.cn`
Microsoft 365 GCC High	`https://outlook.office365.us`
Microsoft 365 DoD	`https://outlook-dod.office365.us`

Die endgültige Anforderungs-URL hängt von Ihrer Umgebung ab und enthält Ihre Mandanten-ID und den Endpunktnamen unter Verwendung der folgenden Syntax:

POST <BaseUrl>/adminapi/v2.0/<TenantID>/<EndpointName>

Zum Beispiel:

POST https://outlook.office365.com/adminapi/v2.0/0550b473-9fd2-4dbb-a058-a1640b4bf458/OrganizationConfig

Anforderungsmodell (Header und Text)

Jeder Exchange Online Admin API-Aufruf verwendet die POST-Methode und folgt einem konsistenten Anforderungsmodell. Der Text muss einen CmdletInput-Umschlag enthalten, der den Cmdlet-Namen und die unterstützten Parameter innerhalb des ausgewählten REST-Endpunkts angibt.

Ausführliche Informationen zu unterstützten Cmdlets und Parametern finden Sie in der Referenz zu Exchange Online Admin API-Endpunkten.

Erforderliche Header:
- Autorisierung: Bearer <access_token>.
- Inhaltstyp: application/json
- X-AnchorMailbox: Ein Routingschlüsselwert, wie im nächsten Abschnitt X-AnchorMailbox-Routinghinweis beschrieben.

Body:

{
  "CmdletInput": {
    "CmdletName": "<Cmdlet Name>",
    "Parameters": {
      /* parameters supported for this cmdlet in the endpoint & their value */
    }
  }
}

Hinweis

Das Übergeben nicht unterstützter Cmdlets oder Parameter für den Endpunkt führt zu dem Fehler 400 Ungültige Anforderung. Überprüfen Sie immer die spezifische Dokumentation des Endpunkts auf zulässige Cmdlets und Parameter.

Beispiel für den ersten Aufruf

Nachdem Sie nun die Anforderungsstruktur und die Header kennen, führen wir Ihren ersten erfolgreichen Aufruf aus. In diesem Beispiel wird die Microsoft 365-Basis-URL verwendet und Ihre organization-Konfiguration abgerufen.

POST https://outlook.office365.com/adminapi/v2.0/12345678-90ab-cdef-1234-567890abcdef/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <appropriate routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-OrganizationConfig"
  }
}

Erwartetes Ergebnis: 200 OK und eine JSON-Nutzlast mit Eigenschaften auf Organisationsebene (z. B MailTipsAllTipsEnabled . und MailTipsExternalRecipientsTipsEnabled).

X-AnchorMailbox-Routinghinweis

Der X-AnchorMailbox-Header ist für alle v2.0 Admin API-Aufrufe obligatorisch. Er stellt einen Routinghinweis bereit, der die Anforderung an den richtigen Back-End-Server weiterleitet. Ohne Routinghinweis können Anforderungen ineffizient weitergeleitet werden oder vollständig fehlschlagen. Die Angabe des richtigen Postfachbezeichners stellt sicher, dass die Anforderung den Basisserver des Postfachs erreicht, die Latenz reduziert, unnötige Hops vermeidet und die Konsistenz verbessert.

Verwenden Sie die folgende Syntax, um der Anforderung den Header hinzuzufügen:

X-AnchorMailbox: <routing key>

Unterstützte Routingschlüsselwerte werden in der folgenden Tabelle beschrieben:

Routingschlüssel	Format	Beispiel
UPN (bevorzugt)	`AAD-UPN:<user@domain>`	`AAD-UPN:alex@contoso.com`
SMTP	`AAD-SMTP:<user@domain>`	`AAD-SMTP:alex@contoso.com`
Microsoft Entra-Objekt-ID/Externe Verzeichnisobjekt-ID (EDOID)	`OID:<ExternalDirectoryObjectId>@<tenantId>`	`OID:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8`
Postfach-GUID	`MBX:<mailboxGuid>@<tenantId>`	`MBX:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8`
Systempostfach (nur App)	`APP:SystemMailbox{<systemMailboxGuid>}@<tenantIdOrOrganization>`	`APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com`

Tipp

Verwenden Sie den UPN für stabilitätsübergreifende Postfachbenennungen. Verwenden Sie das Systempostfachformat für Reine-App-Szenarien.

Wann sollte welcher Routingschlüssel verwendet werden?

Vorgänge, die an ein bestimmtes Postfach gebunden werden: Verwenden Sie für Aufrufe, die auf ein bestimmtes Postfach abzielen ( /Mailbox , /MailboxFolderPermission ), einen Routingschlüssel des Zielpostfachs. Zum Beispiel:
```
X-AnchorMailbox: UPN:alex@contoso.com
```
Alle anderen Vorgänge ohne bestimmtes Postfachziel: Verwenden Sie basierend auf dem Szenario einen der folgenden Schlüssel:
- Delegierter (Benutzer-)Flow: Verwenden Sie einen Routingschlüssel des Administrators, der die API ausführt. Zum Beispiel:
```
X-AnchorMailbox: UPN:admin@contoso.com
```
- Nur-App-Flow: Verwenden Sie einen Routingschlüssel für das Systempostfach des organization. Beispiel:
```
X-AnchorMailbox: APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com
```
  Hinweis
  
  Der GUID-Wert des Systempostfachs ist in allen Organisationen identisch und ist bb558c35-97f1-4cb9-8ff7-d53741dc928c.

Paginierung

Einige Exchange Online Admin API-Endpunkte geben große Ergebnisse zurück. Endpunkte, die paginierung unterstützen, werden in der Dokumentation zu den einzelnen Endpunkten eindeutig identifiziert. Mithilfe der Paginierung können Sie Ergebnisse in kleineren Blöcken abrufen und Timeouts oder Drosselungen vermeiden.

Verwenden Sie den Parameter ResultSize im Anforderungstext, um die Anzahl der Elemente pro Seite anzugeben.
Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort eine @odata.nextLink Eigenschaft mit einer Fortsetzungs-URL.
Um die nächste Seite zu erhalten, post to the @odata.nextLink URL using the same header and authentication.

Wenn Sie den ResultSize-Parameter nicht verwenden, gibt die API standardmäßig maximal 1.000 Einträge zurück. Um alle Einträge in einer einzelnen Anforderung abzurufen, verwenden Sie den Wert Unlimited für den ResultSize-Parameter , wenn der Wert unterstützt wird.

Verwenden Sie die folgenden Methoden für bewährte Methoden bei der Paginierung:

Sorgen Sie dafür, dass Die Parameter für Anforderungen seitenübergreifend konsistent bleiben.
**Das generierte @odata.nextLink ist nur 5-10 Minuten ab dem Zeitpunkt der Generierung gültig. Wenn Sie versuchen, einen abgelaufenen Link zu verwenden, schlägt die Anforderung möglicherweise fehl. Um Fehler zu vermeiden, führen Sie paginierte Aufrufe innerhalb von 5 Minuten nach Empfang der @odata.nextLink Eigenschaft durch.

Beispielanforderung:

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <Routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "ResultSize": 50
    }
  }
}

Nachverfolgungsseite:

POST an die @odata.nextLink URL (verwenden Sie die gleiche Methode).
Ändern Sie keine Parameter zwischen Seiten.

Eigenschaftenauswahl mit $select

Die Exchange Online Admin-API unterstützt den $select Abfrageparameter auf allen Endpunkten. Verwenden Sie $select , um nur die Eigenschaften zurückzugeben, die Sie in der Antwortnutzlast benötigen. Diese Strategie trägt dazu bei, die Größe der Antwort zu reduzieren und den Analyseaufwand auf dem Client zu minimieren.

Wenn eine in der $select -Klausel angegebene Eigenschaft ungültig ist, überspringt der Dienst diese Eigenschaft und gibt die verbleibenden gültigen Eigenschaften zurück.

Fügen Sie $select als Abfrageparameter an die Endpunkt-URL an. Trennen Sie mehrere Eigenschaften durch Kommas:

POST https://<base-url>/adminapi/v2.0/<TenantID>/<EndpointName>?$select=Property1,Property2,...

Ersetzen Sie <beispielsweise TenantID>, <access_token> und <Routingschlüssel> durch die entsprechenden Werte, um nur den Anzeigenamen und die primäre SMTP-Adresse für Postfächer zurückzugeben:

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox?$select=DisplayName,PrimarySmtpAddress
Authorization: Bearer <access_token>
Content-Type: application/json
X-AnchorMailbox: <routing key>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox"
  }
}

Häufige Probleme und deren Behebung

In diesem Abschnitt werden häufige Probleme beschrieben, die bei der Arbeit mit der Exchange Online Admin-API auftreten können.

401 Nicht autorisiert

Ursache:
- Fehlendes, ungültiges oder abgelaufenes OAuth-Token.
- Falscher Bereich.
Behebung:
- Stellen Sie sicher, dass Ihrer App die richtigen Bereiche zugewiesen sind:
  - Delegiert: Exchange.ManageV2.
  - Nur App: Exchange.ManageAsAppV2.
- Rufen Sie ein neues Token ab, falls das ursprüngliche Token abgelaufen ist.
- Vergewissern Sie sich, dass in den Anforderungen die richtigen Mandanten-ID- und App-Registrierungsdetails übergeben werden.

403 Verboten

Ursache: Fehlende RBAC-Rolle oder der Versuch, Objekte außerhalb Ihres Bereichs zu verwalten.
Behebung:
- Weisen Sie dem Benutzer (delegiert) oder dienstprinzipal (nur App) die erforderlichen RBAC-Rollen zu.
- Vergewissern Sie sich, dass sich das Objekt in Ihrem Verwaltungsbereich befindet.

400 Ungültige Anforderung

Ursache: Nicht unterstützter oder falsch formatierter Parameter.
Behebung:
- Überprüfen Sie die Cmdlet-Details für die Kombination aus Endpunkt und Cmdlet.
- Schließen Sie nur Parameter ein, die vom Cmdlet im REST-Endpunkt unterstützt werden.

Falsche Basis-URL

Ursache: Die falsche Basis-URL für Ihre Umgebung.
Korrektur: Verwenden Sie die richtige Basis-URL für Ihre organization.

Paginierungsprobleme

Ursache: Ändern von Parametern zwischen ausgelagerten Aufrufen oder Ignorieren von @odata.nextLink.
Behebung:
- Sorgen Sie für konsistente Parameter auf allen Seiten.
- Post immer an die @odata.nextLink URL.
- Wenn Sie den ResultSize-Parameter nicht verwenden, ist die API standardmäßig auf 1.000 Einträge pro Seite festgelegt.

Routingfehler

Ursache: Fehlender oder falscher X-AnchorMailbox-Header für Vorgänge im Postfachbereich.
Behebung:
- Fügen Sie X-AnchorMailbox in den Postfach-UPN (bevorzugt) oder die SMTP-Adresse ein.
- Überprüfen Sie den Wert, bevor Sie die Anforderung senden.

Bewährte Methoden

Befolgen Sie die Richtlinien in diesem Abschnitt, um eine zuverlässige und effiziente Verwendung der Exchange Online Admin-API sicherzustellen.

Authentifizierung und Sicherheit:
- Verwenden Sie die reine App-Authentifizierung mit Zertifikaten oder verwalteten Identitäten für Produktionsworkloads.
- Fordern Sie nur die Berechtigungen an, die Sie benötigen (Exchange.ManageV2 oder Exchange.ManageAsAppV2).
- Weisen Sie minimale RBAC-Rollen zu, um risiken zu reduzieren.
Anforderungsentwurf:
- Verwenden Sie immer POST für alle Vorgänge, einschließlich Get-*- Cmdlets.
- Schließen Sie nur Parameter ein, die für das Cmdlet in den Endpunkt unterstützt werden.
- Verwenden Sie X-AnchorMailbox für alle Vorgänge.
Leistungsoptimierung:
- Verwenden Sie $select , um die Größe der Antwortnutzlast zu reduzieren.
- Kombinieren mit $select Paginierung für große Datasets.
- Verwenden Sie den ResultSize-Parameter . Andernfalls ist die API standardmäßig auf 1.000 Einträge pro Seite festgelegt.
Resilienz und Fehlerbehandlung:
- Implementieren Sie Wiederholungslogik für die Drosselung (HTTP 429), und berücksichtigen Sie Retry-After.
- Protokollieren sie Anforderungs-IDs aus Fehlerantworten für die Problembehandlung.
- Überprüfen Sie Parameter vor dem Senden von Anforderungen, um 400 ungültige Anforderungen zu vermeiden.
Routing und Umgebungsbewusstsein:
- Verwenden Sie die richtige Basis-URL für Ihre organization.
- Fügen Sie X-AnchorMailbox für alle Anforderungen ein, um Routingfehler zu vermeiden.

Nächste Schritte

Last updated on 2025-11-17

Freigeben über