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 folgenden Aufgaben:

Erstellen einer Anforderung (Header und Text) zum Aufrufen der Exchange Online Admin-API.
Unterstützte Umgebungen und Basis-URLs, die für jede Umgebung verwendet werden sollen.
Funktionsweise der Paginierung und Eigenschaftsauswahl.
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, bestimmte PowerShell-Cmdlets auszuführen und ältere Exchange-Webdienstszenarien (Exchange Web Services, EWS) zu 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 die Berechtigungen auf der Ebene der Organization genehmigt werden.
RBAC-Rollen zuweisen: Weisen Sie dem Benutzer (delegiert) oder dem 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 zu erhalten.
Kennen Sie den Kontext Ihrer organization: Identifizieren Sie Ihre TenantID (GUID) und 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 mit 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 Textkörper muss einen CmdletInput-Umschlag enthalten, der den Namen des Cmdlets und unterstützte Parameter innerhalb des ausgewählten REST-Endpunkts angibt.

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

Erforderliche Header:
- Autorisierung: Bearer <access_token>.
- Content-Type: application/json
- X-AnchorMailbox: Ein Routingschlüsselwert, wie im kommenden 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 folgendem Fehler: 400 Bad Request. Überprüfen Sie immer die spezifische Dokumentation des Endpunkts auf zulässige Cmdlets und Parameter.

Beispiel für einen ersten Aufruf

Nachdem Sie nun die Anforderungsstruktur und die Header kennen, lassen Sie uns Ihren ersten erfolgreichen Aufruf durchführen. In diesem Beispiel wird die Microsoft 365-Basis-URL verwendet und die Konfiguration Ihrer organization 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, MailTipsAllTipsEnabled die Eigenschaften auf Organisationsebene enthält (z. B. und MailTipsExternalRecipientsTipsEnabled).

X-AnchorMailbox-Routinghinweis

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

Verwenden Sie die folgende Syntax, um die Kopfzeile zu Ihrer Anforderung hinzuzufügen:

X-AnchorMailbox: <routing key>

In der folgenden Tabelle werden die unterstützten Routingschlüsselwerte 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 UPN für Stabilität bei Postfachumbenennungen. Verwenden Sie das Systempostfachformat für reine App-Szenarien.

Wann welcher Routingschlüssel verwendet werden sollte

Vorgänge, die an ein bestimmtes Postfach gebunden sind: Verwenden Sie für Anrufe, 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 spezifisches Postfachziel: Verwenden Sie je nach Szenario einen der folgenden Schlüssel:
- Delegierter (Benutzer-)Fluss: Verwenden Sie einen Routingschlüssel des Administrators, der die API ausführt. Zum Beispiel:
```
X-AnchorMailbox: UPN:admin@contoso.com
```
- App-only-Flow: Verwenden Sie einen Routingschlüssel für das Systempostfach der 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 lautet bb558c35-97f1-4cb9-8ff7-d53741dc928c.

Paginierung

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

Um die Anzahl der Elemente pro Seite anzugeben, verwenden Sie den Parameter ResultSize in Ihrem Anforderungstext.
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 an die @odata.nextLink URL mit denselben Headern und derselben Authentifizierung senden.

Wenn Sie den Parameter "Ergebnisgröße " 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 Parameter ResultSize, sofern der Wert unterstützt wird.

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

Parameter für Anforderungen seitenübergreifend konsistent halten.
**Das Generierte @odata.nextLink ist nur für 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, schließen Sie paginierte Anrufe innerhalb von 5 Minuten nach Erhalt der @odata.nextLink Eigenschaft ab.

Beispiel für Anforderung:

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
    }
  }
}

Folgeseite:

POST an die @odata.nextLink URL senden (verwenden Sie dieselbe Methode).
Parameter nicht zwischen Seiten ändern.

Unterkunftsauswahl mit $select

Die Exchange Online Admin API unterstützt den $select Abfrageparameter auf allen Endpunkten. Wird verwendet $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 für den 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.

Als Abfrageparameter an die Endpunkt-URL anfügen $select . 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 wie man sie behebt

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.
Problembehebung:
- Stellen Sie sicher, dass Ihrer App die richtigen Bereiche zugewiesen sind:
  - Delegiert: Exchange.ManageV2.
  - Nur App: Exchange.ManageAsAppV2.
- Beziehen Sie ein neues Token für den Fall, dass das ursprüngliche Token abgelaufen ist.
- Überprüfen Sie, ob die richtigen TenantID- und App-Registrierungsdetails in den Anforderungen übergeben werden.

403 Verboten

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

400 Bad Request (400 ungültige Anforderung)

Ursache: Nicht unterstützter oder falsch formatierter Parameter.
Problembehebung:
- Überprüfen Sie die Cmdlet-Details für die Kombination aus Endpunkt und Cmdlet.
- Schließen Sie nur vom Cmdlet unterstützte Parameter in den REST-Endpunkt ein.

Falsche Basis-URL

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

Probleme mit Paginierung

Ursache: Ändern von Parametern zwischen ausgelagerten Aufrufen oder Ignorieren von @odata.nextLink.
Problembehebung:
- Parameter über alle Seiten hinweg konsistent halten.
- Immer an die @odata.nextLink URL POSTEN.
- Wenn Sie den Parameter "ResultSize" nicht verwenden, verwendet die API standardmäßig 1.000 Einträge pro Seite.

Routingfehler

Ursache: Fehlender oder falscher X-AnchorMailbox-Header für Vorgänge im Postfachbereich.
Problembehebung:
- Schließen Sie X-AnchorMailbox mit dem Postfach-UPN (bevorzugt) oder der 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 Nutzung der Exchange Online Admin-API sicherzustellen.

Authentifizierung und Sicherheit:
- Verwenden Sie für Produktionsworkloads die reine App-Authentifizierung mit Zertifikaten oder verwalteten Identitäten.
- 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.
Design anfordern:
- Verwenden Sie POST immer für alle Vorgänge, einschließlich Get-*- Cmdlets.
- Schließen Sie nur Parameter ein, die für das Cmdlet im Endpunkt unterstützt werden.
- Verwenden Sie X-AnchorMailbox für alle Vorgänge.
Performance Optimization:
- Wird verwendet $select , um die Größe der Antwortnutzlast zu reduzieren.
- Kombinieren mit $select Paginierung für große Datensätze.
- Verwenden Sie den Parameter ResultSize . Andernfalls verwendet die API standardmäßig 1.000 Einträge pro Seite.
Resilienz und Fehlerbehandlung:
- Implementieren Sie eine Wiederholungslogik für die Drosselung (HTTP 429), und berücksichtigen Sie Wiederholungsversuche.
- Protokollieren Sie Anforderungs-IDs aus Fehlerantworten zur Problembehandlung.
- Überprüfen Sie die Parameter vor dem Senden von Anforderungen, um 400 ungültige Anforderungen zu vermeiden.
Routing und Umweltbewusstsein:
- Verwenden Sie die richtige Basis-URL für Ihre organization.
- Schließen Sie "X-AnchorMailbox " für alle Anforderungen ein, um Routingfehler zu vermeiden.

Nächste Schritte

Zuletzt aktualisiert um 2026-09-25