Partager via

Prise en main de l’API Exchange Online Administration

Remarque

Les fonctionnalités décrites dans cet article sont actuellement en préversion, ne sont pas disponibles dans toutes les organisations et sont susceptibles d’être modifiées.

Cet article vous montre comment effectuer votre premier appel d’API Exchange Online Administration réussi et explique les principaux comportements et modèles qui s’appliquent à tous les points de terminaison.

Cet article vous aide à effectuer les tâches suivantes :

  • Comment former une demande (en-têtes et corps) pour appeler l’API Exchange Online Administration.
  • Environnements et URL de base pris en charge à utiliser pour chaque environnement.
  • Fonctionnement de la pagination et de la sélection de propriétés.
  • Quand et comment utiliser X-AnchorMailbox pour le routage.
  • Problèmes courants et meilleures pratiques.

L’API Exchange Online Administration fournit un moyen basé sur REST d’exécuter des applets de commande PowerShell spécifiques, en remplaçant les scénarios EWS (Exchange Web Services) hérités. Pour plus d’informations, consultez Vue d’ensemble de l’API Exchange Online Administration.

Prérequis : Configurer l’authentification et les autorisations

Avant de pouvoir effectuer votre premier appel à l’API Exchange Online Administration, vous devez configurer l’authentification et les autorisations afin que votre application ou votre script puisse accéder en toute sécurité à votre organization. Pour obtenir des instructions complètes, consultez Authentification et autorisation pour l’API Exchange Online Administration.

Voici les étapes résumées :

  1. Inscrire une application dans Microsoft Entra ID : créez une inscription d’application pour un accès délégué ou uniquement à l’application.
  2. Accordez des autorisations d’API :
    • Délégué : Exchange.ManageV2.
    • Application uniquement : Exchange.ManageAsAppV2.
  3. Obtenir le consentement de l’administrateur : vérifiez que les autorisations sont autorisées au niveau organization.
  4. Attribuer des rôles RBAC : attribuez des rôles à l’utilisateur (délégué) ou au principal de service (application uniquement) qui couvrent les objets que vous gérez.
  5. Acquérir un jeton d’accès : utilisez des flux délégués ou d’application uniquement pour obtenir un jeton OAuth valide.
  6. Connaître votre contexte organization : identifiez votre ID de locataire (GUID) et votre URL de base.

Environnements et URL de base pris en charge

L’API Exchange Online Administration est disponible dans tous les environnements Exchange Online. Chaque environnement utilise une URL de base différente pour les requêtes. Veillez donc à utiliser l’URL appropriée pour votre environnement, comme décrit dans le tableau suivant :

Environnement URL de base
Microsoft 365 ou Microsoft 365 GCC https://outlook.office365.com
Office 365 exploité par 21Vianet (Chine) https://outlook.office365.cn
Microsoft 365 GCC High https://outlook.office365.us
Microsoft 365 DoD https://outlook-dod.office365.us

L’URL de la demande finale dépend de votre environnement et inclut votre TenantID et le nom du point de terminaison à l’aide de la syntaxe suivante :

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

Par exemple :

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

Modèle de requête (en-têtes et corps)

Chaque appel d’API Exchange Online Administration utilise la méthode POST et suit un modèle de requête cohérent. Le corps doit inclure une enveloppe CmdletInput qui spécifie le nom de l’applet de commande et les paramètres pris en charge dans le point de terminaison REST sélectionné.

Pour plus d’informations sur les applets de commande et les paramètres pris en charge, consultez Exchange Online Administration informations de référence sur les points de terminaison d’API.

  • En-têtes obligatoires :

    • Autorisation : Bearer <access_token>.
    • Content-Type : application/json
    • X-AnchorMailbox : valeur de clé de routage décrite dans la prochaine section indicateur de routage X-AnchorMailbox .

  • Body :

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

Remarque

Le passage d’applets de commande ou de paramètres non pris en charge pour le point de terminaison entraîne l’erreur : 400 Demande incorrecte. Toujours case activée la documentation spécifique du point de terminaison pour les applets de commande et les paramètres autorisés.

Exemple de premier appel

Maintenant que vous connaissez la structure des demandes et les en-têtes, nous allons effectuer votre premier appel réussi. Cet exemple utilise l’URL de base Microsoft 365 et récupère votre configuration organization.

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

Résultat attendu : 200 OK et une charge utile JSON contenant des propriétés au niveau de l’organisation (par exemple, MailTipsAllTipsEnabled et MailTipsExternalRecipientsTipsEnabled).

Indicateur de routage X-AnchorMailbox

L’en-tête X-AnchorMailbox est obligatoire pour tous les appels d’API Administration v2.0. Il fournit un indicateur de routage qui dirige la requête vers le serveur principal approprié. Sans indicateur de routage, les requêtes peuvent être routées de manière inefficace ou échouer complètement. Le fait de fournir l’identificateur de boîte aux lettres correct garantit que la demande atteint le serveur d’accueil de la boîte aux lettres, réduit la latence, évite les sauts inutiles et améliore la cohérence.

Pour ajouter l’en-tête à votre demande, utilisez la syntaxe suivante :

X-AnchorMailbox: <routing key>

Les valeurs de clé de routage prises en charge sont décrites dans le tableau suivant :

Clé de routage Format Exemple
UPN (préféré) AAD-UPN:<user@domain> AAD-UPN:alex@contoso.com
SMTP AAD-SMTP:<user@domain> AAD-SMTP:alex@contoso.com
ID d’objet Microsoft Entra/ID d’objet répertoire externe (EDOID) OID:<ExternalDirectoryObjectId>@<tenantId> OID:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8
GUID de la boîte aux lettres MBX:<mailboxGuid>@<tenantId> MBX:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8
Boîte aux lettres système (application uniquement) APP:SystemMailbox{<systemMailboxGuid>}@<tenantIdOrOrganization> APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com

Conseil

Utilisez UPN pour la stabilité entre les renommages de boîtes aux lettres. Utilisez le format de boîte aux lettres système pour les scénarios d’application uniquement.

Quand utiliser la clé de routage

  • Opérations liées à une boîte aux lettres particulière : pour les appels qui ciblent une boîte aux lettres spécifique ( /Mailbox , /MailboxFolderPermission ), utilisez une clé de routage de la boîte aux lettres cible. Par exemple :

    X-AnchorMailbox: UPN:alex@contoso.com

  • Toutes les autres opérations sans cible de boîte aux lettres spécifique : utilisez l’une des clés suivantes en fonction du scénario :

    • Flux délégué (utilisateur) : utilisez une clé de routage de l’administrateur qui exécute l’API. Par exemple :

      X-AnchorMailbox: UPN:admin@contoso.com

    • Flux d’application uniquement : utilisez une clé de routage pour la boîte aux lettres système de l’organization. Par exemple :

      X-AnchorMailbox: APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com

      Remarque

      La valeur GUID de boîte aux lettres système est la même pour toutes les organisations et est bb558c35-97f1-4cb9-8ff7-d53741dc928c.

Pagination

Certains points de terminaison d’API Exchange Online Administration retournent des résultats volumineux. Les points de terminaison qui prennent en charge la pagination sont clairement identifiés dans la documentation des points de terminaison individuels. La pagination vous permet de récupérer les résultats en blocs plus petits et d’éviter les délais d’attente ou les limitations.

  • Pour spécifier le nombre d’éléments par page, utilisez le paramètre ResultSize dans le corps de votre demande.
  • Si d’autres résultats sont disponibles, la réponse inclut une @odata.nextLink propriété avec une URL de continuation.
  • Pour obtenir la page suivante, postez sur l’URL à l’aide @odata.nextLink des mêmes en-têtes et de la même authentification.

Si vous n’utilisez pas le paramètre ResultSize , l’API retourne un maximum de 1 000 entrées par défaut. Pour récupérer toutes les entrées d’une seule requête, utilisez la valeur Unlimited du paramètre ResultSize si la valeur est prise en charge.

Utilisez les méthodes suivantes pour connaître les meilleures pratiques en matière de pagination :

  • Conservez la cohérence des paramètres pour les demandes entre les pages.
  • **Le généré @odata.nextLink est valide uniquement pendant 5 à 10 minutes à partir du moment de la génération. Si vous essayez d’utiliser un lien arrivé à expiration, la demande peut échouer. Pour éviter les erreurs, effectuez les appels paginés dans les 5 minutes suivant la réception de la @odata.nextLink propriété.

Exemple de demande :

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

Page de suivi :

  • POST vers l’URL @odata.nextLink (utilisez la même méthode).
  • Ne modifiez pas les paramètres entre les pages.

Sélection de propriété avec $select

L’API Exchange Online Administration prend en charge le paramètre de $select requête sur tous les points de terminaison. Utilisez $select pour renvoyer uniquement les propriétés dont vous avez besoin dans la charge utile de réponse. Cette stratégie permet de réduire la taille de la réponse et de réduire la surcharge d’analyse sur le client.

Si une propriété spécifiée dans la $select clause n’est pas valide, le service ignore cette propriété et retourne les propriétés valides restantes.

Ajoutez $select en tant que paramètre de requête à l’URL du point de terminaison. Séparez plusieurs propriétés par des virgules :

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

Par exemple, remplacez <TenantID>, <access_token> et <clé> de routage par les valeurs appropriées pour renvoyer uniquement le nom d’affichage et l’adresse SMTP principale pour les boîtes aux lettres :

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

Problèmes courants et comment les résoudre

Cette section décrit les problèmes fréquents que vous pouvez rencontrer lors de l’utilisation de l’API Exchange Online Administration.

401 Non autorisé

  • Cause :
    • Jeton OAuth manquant, non valide ou expiré.
    • Étendue incorrecte.
  • Correctif :
    • Vérifiez que les étendues appropriées sont affectées à votre application :
      • Délégué : Exchange.ManageV2.
      • Application uniquement : Exchange.ManageAsAppV2.
    • Acquérir un nouveau jeton au cas où le jeton d’origine a expiré.
    • Vérifiez que l’ID de locataire et les détails d’inscription de l’application sont transmis dans les demandes.

403 Interdit

  • Cause : rôle RBAC manquant ou tentative de gestion d’objets en dehors de votre étendue.
  • Correctif :
    • Attribuez les rôles RBAC requis à l’utilisateur (délégué) ou au principal de service (application uniquement).
    • Vérifiez que l’objet se trouve dans votre étendue de gestion.

400 Demande incorrecte

  • Cause : paramètre non pris en charge ou mis en forme de manière incorrecte.
  • Correctif :
    • Vérifiez les détails de l’applet de commande pour la combinaison de point de terminaison et d’applet de commande.
    • Incluez uniquement les paramètres pris en charge par l’applet de commande dans le point de terminaison REST.

URL de base incorrecte

Problèmes de pagination

  • Cause : modification des paramètres entre les appels paginés ou l’ignorance de @odata.nextLink.
  • Correctif :
    • Conservez la cohérence des paramètres sur toutes les pages.
    • Toujours POST vers l’URL @odata.nextLink .
    • Si vous n’utilisez pas le paramètre ResultSize , l’API utilise par défaut 1 000 entrées par page.

Erreurs de routage

  • Cause : En-tête X-AnchorMailbox manquant ou incorrect pour les opérations délimitées aux boîtes aux lettres.
  • Correctif :
    • Incluez X-AnchorMailbox avec l’UPN de boîte aux lettres (par défaut) ou l’adresse SMTP.
    • Validez la valeur avant d’envoyer la requête.

Meilleures pratiques

Suivez les instructions de cette section pour garantir une utilisation fiable et efficace de l’API Exchange Online Administration.

  • Authentification et sécurité :

    • Utilisez l’authentification d’application uniquement avec des certificats ou des identités managées pour les charges de travail de production.
    • Demandez uniquement les autorisations dont vous avez besoin (Exchange.ManageV2 ou Exchange.ManageAsAppV2).
    • Attribuez des rôles RBAC minimaux pour réduire les risques.

  • Conception de la demande :

    • Utilisez toujours POST pour toutes les opérations, y compris les applets de commande Get-* .
    • Incluez uniquement les paramètres pris en charge pour l’applet de commande dans le point de terminaison.
    • Utilisez X-AnchorMailbox pour toutes les opérations.

  • Optimisation des performances :

    • Utilisez $select pour réduire la taille de la charge utile de réponse.
    • Combinez $select avec la pagination pour les jeux de données volumineux.
    • Utilisez le paramètre ResultSize . Sinon, l’API est définie par défaut sur 1 000 entrées par page.

  • Résilience et gestion des erreurs :

    • Implémentez une logique de nouvelle tentative pour la limitation (HTTP 429) et respectez Retry-After.
    • Journaliser les ID de demande à partir des réponses d’erreur pour la résolution des problèmes.
    • Validez les paramètres avant d’envoyer des demandes pour éviter 400 requête incorrecte.

  • Reconnaissance du routage et de l’environnement :

    • Utilisez l’URL de base correcte pour votre organization.
    • Incluez X-AnchorMailbox pour toutes les requêtes afin d’éviter les erreurs de routage.

Étapes suivantes

  • Last updated on