Partager via

Point de terminaison de boîte aux lettres dans 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.

Le point de terminaison de boîte aux lettres dans l’API Exchange Online Administration vous permet d’afficher et de gérer les délégués Envoyer de la part.

Les cas d’usage classiques sont les suivants :

  • Répertorier les boîtes aux lettres ou récupérer les détails d’une boîte aux lettres spécifique.
  • Inspectez la configuration des délégués pour SendOnBehalfTo, y compris les noms d’affichage facultatifs pour les délégués.
  • Mettez à jour l’envoi de la part des délégués en remplaçant la liste complète des délégués ou en apportant des modifications incrémentielles (ajout/suppression).

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.

URL du point de terminaison

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/Mailbox

Conseil

Utilisez l’URL de base pour votre environnement, comme décrit dans Environnements et URL de base pris en charge.

Modèle de demande

En-têtes

Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <routing hint>

Pour connaître les valeurs X-AnchorMailbox , consultez Indicateur de routage X-AnchorMailbox.

Corps

  • Get-Mailbox :

    {
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                        //optional
      "ResultSize": <Integer | "Unlimited">,                 //optional (pagination)
      "IncludeGrantSendOnBehalfTowithDisplayNames": true     //optional
    }
  }
}

  • Set-Mailbox (remplacer les délégués) :

    {
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",      //required
      "GrantSendOnBehalfTo": [             //required
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

  • Set-Mailbox (ajouter/supprimer des délégués) :

    {
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",                //required
      "GrantSendOnBehalfTo": {                       //required
        "add": ["delegate3@contoso.com"],
        "remove": ["delegate1@contoso.com"],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}

Pagination

Le paramètre ResultSize sur l’applet de commande Get-Mailbox contrôle la pagination. Par défaut, jusqu’à 1 000 résultats sont retournés.

Si d’autres résultats sont disponibles, la réponse inclut une @odata.nextLink propriété avec une URL de continuation. Pour extraire la page suivante, émettez une nouvelle requête POST à l’URL dans @odata.nextLink avec le même corps.

Sélection de propriété

Ce point de terminaison prend en charge le $select paramètre de requête pour retourner uniquement des propriétés spécifiques dans la réponse.

Applets de commande et paramètres pris en charge

La liste suivante décrit les applets de commande et les paramètres pris en charge par ce point de terminaison. D’autres applets de commande dans le corps de ce point de terminaison entraînent une erreur.

  • Get-Mailbox :

    Seuls les paramètres de Get-Mailbox décrits dans le tableau suivant sont disponibles via le point de terminaison REST :

    Paramètre Obligatoire Type Description
    Identité Facultatif String Spécifie la boîte aux lettres sur laquelle récupérer des informations. Les valeurs valides sont le nom, le nom unique, l’alias, le nom d’utilisateur principal (UPN), le GUID ou tout autre identificateur unique. Si elle est omise et soumise à ResultSize, l’applet de commande retourne toutes les boîtes aux lettres.
    ResultSize Facultatif Entier ou Illimité Limite le nombre de résultats retournés. Les valeurs valides sont un entier (par exemple, 10) ou la valeur "Unlimited".
    IncludeGrantSendOnBehalfToWithDisplayNames Facultatif Booléen La valeur True inclut les entrées de délégué SendOnBehalfTo avec leurs noms d’affichage.

    REMARQUE : Ce paramètre est en cours de déploiement par étapes et peut ne pas être disponible dans toutes les organisations.

  • Set-Mailbox :

    Seuls les paramètres de Set-Mailbox décrits dans le tableau suivant sont disponibles via le point de terminaison REST :

    Paramètre Obligatoire Type Description
    Identité Facultatif String Spécifie la boîte aux lettres cible. Les valeurs valides sont le nom, le nom unique, l’alias, l’UPN, le GUID ou tout autre identificateur unique.
    GrantSendOnBehalfTo Requis Collection ou table de hachage
    • Remplacer : liste d’adresses SMTP pour la liste complète des délégués. Par exemple : ["bob@contoso.com","carol@contoso.com"].
    • Ajout/suppression : table de hachage avec add et/ou remove des tableaux pour modifier la liste des délégués. Par exemple : { "add" : ["dave@contoso.com"], remove : ["carol@contoso.com"] }.

Vue d’ensemble de la réponse

Remarque

Pendant la préversion, le point de terminaison inclut la sortie complète de l’applet de commande Get-Mailbox dans la réponse de l’API. Pendant la transition vers la mise en production publique, la réponse sera limitée aux propriétés principales répertoriées dans cette section (propriétés nécessaires pour le scénario équivalent à EWS). Nous vous recommandons d’utiliser uniquement les propriétés répertoriées dans cette section. Nous allons documenter les modifications apportées aux propriétés disponibles.

  • La réponse Get-Mailbox est un objet JSON ou un tableau de listes avec des propriétés de boîte aux lettres. Les propriétés suivantes sont renvoyées:

    • Identité : identificateur canonique de la boîte aux lettres (souvent l’alias ou le nom unique).
    • ID : identificateur de service pour l’objet de boîte aux lettres.
    • Nom : nom d’affichage Exchange unique pour la boîte aux lettres.
    • DisplayName : nom d’affichage convivial.
    • UserPrincipalName : compte associé à la boîte aux lettres.
    • Alias : alias de boîte aux lettres unique.
    • ExternalDirectoryObjectId : guid d’objet Microsoft Entra ID pour la boîte aux lettres.
    • RecipientType : pour connaître les valeurs de boîte aux lettres possibles, consultez RecipientType.
    • RecipientTypeDetails : pour connaître les valeurs de boîte aux lettres possibles, consultez RecipientTypeDetails.
    • EmailAddresses : toutes les adresses proxy du destinataire (y compris les entrées SMTP : et smtp :).
    • PrimarySmtpAddress : adresse SMTP principale du destinataire (correspond à la valeur SMTP : dans EmailAddresses).
    • MaxSendSize : taille maximale des messages que la boîte aux lettres peut envoyer.
    • GrantSendOnBehalfTo : liste des délégués (adresses SMTP) accordés aux autorisations Envoyer de la part pour la boîte aux lettres.
    • GrantSendOnBehalfToWithDisplayNames : même liste avec les noms complets délégués (si demandé).

  • L’applet de commande Set-Mailbox retourne HTTP 200 OK en cas de réussite. Aucun corps de réponse n’est requis pour les mises à jour réussies.

Exemples

  • Exemple 1 : Get-Mailbox simple (liste paginée) :

    Cet exemple répertorie les 10 premières boîtes aux lettres du organization. Utilisez @odata.nextLink pour continuer.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

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

  • Exemple 2 : Get-Mailbox pour une boîte aux lettres spécifique et inclure des noms complets délégués :

    Cet exemple retourne les détails de la boîte aux lettres et les délégués SendOnBehalfTo avec des noms complets.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Get-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "IncludeGrantSendOnBehalfTowithDisplayNames": true
    }
  }
}

  • Exemple 3 : Set-Mailbox : Remplacer la liste des délégués :

    Cet exemple remplace la liste SendOnBehalfTo sur la boîte aux lettres spécifiée par les délégués spécifiés.

    Le résultat est : 200 OK. delegate1@contoso.com et delegate2@contoso.com remplacez tous les délégués SendOnBehalfTo existants sur la boîte aux lettres.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo@odata.type": "#Collection(String)",
      "GrantSendOnBehalfTo": [
        "delegate1@contoso.com",
        "delegate2@contoso.com"
      ]
    }
  }
}

  • Exemple 4 : Set-Mailbox : ajouter des délégués à la liste de délégués existante :

    Cet exemple ajoute de nouveaux délégués SendOnBehalfTo à la boîte aux lettres spécifiée tout en conservant les délégués existants.

    Le résultat est : 200 OK. delegate3@contoso.com et delegate4@contoso.com sont ajoutés à la liste existante des délégués sur la boîte aux lettres.

    POST /adminapi/v2.0/<TenantID>/Mailbox HTTP/1.1
Host: outlook.office365.com
Authorization: Bearer <auth token>
Content-Type: application/json
X-AnchorMailbox: <Routing Hint>

{
  "CmdletInput": {
    "CmdletName": "Set-Mailbox",
    "Parameters": {
      "Identity": "alex@contoso.com",
      "GrantSendOnBehalfTo": {
        "add": [
          "delegate3@contoso.com",
          "delegate4@contoso.com"
        ],
        "@odata.type": "#Exchange.GenericHashTable"
      }
    }
  }
}
  • Last updated on