Compartir a través de

Introducción a la API de Exchange Online Administración

Nota:

Las características descritas en este artículo están actualmente en versión preliminar, no están disponibles en todas las organizaciones y están sujetas a cambios.

En este artículo se muestra cómo realizar la primera llamada Exchange Online Administración API correcta y se explican los comportamientos y patrones clave que se aplican en todos los puntos de conexión.

Este artículo le ayuda con las siguientes tareas:

  • Cómo formar una solicitud (encabezados y cuerpo) para llamar a la API de Exchange Online Administración.
  • Entornos admitidos y direcciones URL base que se van a usar para cada entorno.
  • Cómo funcionan la paginación y la selección de propiedades.
  • Cuándo y cómo usar X-AnchorMailbox para el enrutamiento.
  • Problemas comunes y procedimientos recomendados.

La API de Exchange Online Administración proporciona una manera basada en REST de ejecutar cmdlets de PowerShell específicos, reemplazando escenarios heredados de Exchange Web Services (EWS). Para obtener más información, consulte Introducción a la API de Exchange Online Administración.

Requisito previo: Configuración de la autenticación y los permisos

Para poder realizar la primera llamada a la API de Exchange Online Administración, debe configurar la autenticación y los permisos para que la aplicación o el script puedan acceder de forma segura a su organización. Para obtener instrucciones completas, consulte Autenticación y autorización para la API de Exchange Online Administración.

Estos son los pasos resumidos:

  1. Registrar una aplicación en Microsoft Entra ID: cree un registro de aplicación para el acceso delegado o solo para la aplicación.
  2. Concesión de permisos de API:
    • Delegado: Exchange.ManageV2.
    • Solo aplicación: Exchange.ManageAsAppV2.
  3. Obtener el consentimiento del administrador: asegúrese de que los permisos están consentidos en el nivel de organización.
  4. Asignar roles de RBAC: asigne roles al usuario (delegado) o a la entidad de servicio (solo aplicación) que cubren los objetos que administra.
  5. Adquirir un token de acceso: use flujos delegados o solo de aplicación para obtener un token de OAuth válido.
  6. Conocer el contexto de la organización: identifique el identificador de inquilino (GUID) y la dirección URL base.

Entornos admitidos y direcciones URL base

La API de Exchange Online Administración está disponible en todos los entornos de Exchange Online. Cada entorno usa una dirección URL base diferente para las solicitudes, por lo que asegúrese de usar la dirección URL correcta para su entorno, tal como se describe en la tabla siguiente:

Entorno Dirección URL base
Microsoft 365 o Microsoft 365 GCC https://outlook.office365.com
Office 365 opera 21Vianet (China) https://outlook.office365.cn
Microsoft 365 GCC High https://outlook.office365.us
Microsoft 365 DoD https://outlook-dod.office365.us

La dirección URL de la solicitud final depende del entorno e incluye tenantID y el nombre del punto de conexión mediante la sintaxis siguiente:

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

Por ejemplo:

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

Modelo de solicitud (encabezados y cuerpo)

Cada llamada Exchange Online Administración API usa el método POST y sigue un modelo de solicitud coherente. El cuerpo debe incluir un sobre CmdletInput que especifique el nombre del cmdlet y los parámetros admitidos en el punto de conexión REST seleccionado.

Para obtener más información sobre los cmdlets y parámetros admitidos, consulte Exchange Online Administración referencia de puntos de conexión de API.

  • Encabezados necesarios:

    • Autorización: Bearer <access_token>.
    • Tipo de contenido: application/json
    • X-AnchorMailbox: un valor de clave de enrutamiento como se describe en la próxima sección de sugerencias de enrutamiento X-AnchorMailbox .

  • Body:

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

Nota:

Al pasar cmdlets o parámetros no admitidos para el punto de conexión, se produce el error: 400 Solicitud incorrecta. Compruebe siempre la documentación específica del punto de conexión para ver los cmdlets y parámetros permitidos.

Primer ejemplo de llamada

Ahora que conoce la estructura y los encabezados de la solicitud, vamos a realizar la primera llamada correcta. En este ejemplo se usa la dirección URL base de Microsoft 365 y se recupera la configuración de la organización.

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

Resultado esperado: 200 OK y una carga JSON que contiene propiedades de nivel de organización (por ejemplo, MailTipsAllTipsEnabled y MailTipsExternalRecipientsTipsEnabled).

Sugerencia de enrutamiento X-AnchorMailbox

El encabezado X-AnchorMailbox es obligatorio para todas las llamadas api de Administración v2.0. Proporciona una sugerencia de enrutamiento que dirige la solicitud al servidor back-end correcto. Sin una sugerencia de enrutamiento, las solicitudes se pueden enrutar ineficazmente o producir un error por completo. Proporcionar el identificador de buzón correcto garantiza que la solicitud llegue al servidor principal del buzón, reduce la latencia, evita saltos innecesarios y mejora la coherencia.

Para agregar el encabezado a la solicitud, use la sintaxis siguiente:

X-AnchorMailbox: <routing key>

Los valores de clave de enrutamiento admitidos se describen en la tabla siguiente:

Clave de enrutamiento Formato Ejemplo
UPN (preferido) AAD-UPN:<user@domain> AAD-UPN:alex@contoso.com
SMTP AAD-SMTP:<user@domain> AAD-SMTP:alex@contoso.com
Microsoft Entra id. de objeto o identificador de objeto de directorio externo (EDOID) OID:<ExternalDirectoryObjectId>@<tenantId> OID:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8
GUID del buzón de correo MBX:<mailboxGuid>@<tenantId> MBX:80db1853-38c7-4ff3-945b-1e9a78119cb0@ab9f5dac-33ac-4f91-a9f4-8720b942f1a8
Buzón del sistema (solo aplicación) APP:SystemMailbox{<systemMailboxGuid>}@<tenantIdOrOrganization> APP:SystemMailbox{bb558c35-97f1-4cb9-8ff7-d53741dc928c}@contoso.onmicrosoft.com

Sugerencia

Use UPN para la estabilidad en los nombres de buzón. Use el formato de buzón del sistema para escenarios de solo aplicación.

Cuándo usar la clave de enrutamiento

  • Operaciones que se enlazan a un buzón determinado: para las llamadas que tienen como destino un buzón específico ( /Mailbox , /MailboxFolderPermission ), use una clave de enrutamiento del buzón de destino. Por ejemplo:

    X-AnchorMailbox: UPN:alex@contoso.com

  • Todas las demás operaciones sin un destino de buzón específico: use una de las claves siguientes en función del escenario:

    • Flujo delegado (usuario): use una clave de enrutamiento del administrador que ejecuta la API. Por ejemplo:

      X-AnchorMailbox: UPN:admin@contoso.com

    • Flujo de solo aplicación: use una clave de enrutamiento para el buzón del sistema de la organización. Por ejemplo:

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

      Nota:

      El valor guid del buzón de correo del sistema es el mismo en todas las organizaciones y es bb558c35-97f1-4cb9-8ff7-d53741dc928c.

Paginación

Algunos puntos de conexión de API de Exchange Online Administración devuelven resultados grandes. Los puntos de conexión que admiten la paginación se identifican claramente en la documentación de puntos de conexión individuales. La paginación le ayuda a recuperar los resultados en fragmentos más pequeños y a evitar tiempos de espera o limitación.

  • Para especificar el número de elementos por página, use el parámetro ResultSize en el cuerpo de la solicitud.
  • Si hay más resultados disponibles, la respuesta incluye una @odata.nextLink propiedad con una dirección URL de continuación.
  • Para obtener la página siguiente, POST a la @odata.nextLink dirección URL con los mismos encabezados y autenticación.

Si no usa el parámetro ResultSize , la API devuelve un máximo de 1000 entradas de forma predeterminada. Para recuperar todas las entradas de una sola solicitud, use el valor Unlimited del parámetro ResultSize si se admite el valor.

Use los métodos siguientes para los procedimientos recomendados con paginación:

  • Mantenga los parámetros coherentes para las solicitudes entre páginas.
  • **El generado @odata.nextLink solo es válido durante 5-10 minutos a partir del momento de la generación. Si intenta usar un vínculo expirado, es posible que se produzca un error en la solicitud. Para evitar errores, complete las llamadas paginadas en un plazo de 5 minutos después de recibir la @odata.nextLink propiedad.

Solicitud de ejemplo:

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

Página de seguimiento:

  • POST en la dirección URL (use el @odata.nextLink mismo método).
  • No cambie los parámetros entre páginas.

Selección de propiedades con $select

La API de Exchange Online Administración admite el parámetro de $select consulta en todos los puntos de conexión. Use $select para devolver solo las propiedades que necesita en la carga de respuesta. Esta estrategia ayuda a reducir el tamaño de la respuesta y minimiza la sobrecarga de análisis en el cliente.

Si una propiedad especificada en la $select cláusula no es válida, el servicio omite esa propiedad y devuelve las propiedades válidas restantes.

Anexe $select como parámetro de consulta a la dirección URL del punto de conexión. Separe varias propiedades con comas:

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

Por ejemplo, reemplace <TenantID>, <access_token> y <clave> de enrutamiento por los valores adecuados para devolver solo el nombre para mostrar y la dirección SMTP principal para los buzones:

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

Problemas comunes y cómo corregirlos

En esta sección se describen los problemas frecuentes que puede encontrar al trabajar con la API de Exchange Online Administración.

401 No autorizado

  • Causa:
    • Token de OAuth que falta, no es válido o ha expirado.
    • Ámbito incorrecto.
  • Corrección:
    • Asegúrese de que la aplicación tiene asignados los ámbitos correctos:
      • Delegado: Exchange.ManageV2.
      • Solo aplicación: Exchange.ManageAsAppV2.
    • Adquiera un nuevo token en caso de que el token original haya expirado.
    • Compruebe que los detalles correctos de TenantID y registro de aplicaciones se pasan en las solicitudes.

403 Prohibido

  • Causa: falta el rol RBAC o intenta administrar objetos fuera del ámbito.
  • Corrección:
    • Asigne los roles de RBAC necesarios al usuario (delegado) o a la entidad de servicio (solo aplicación).
    • Confirme que el objeto está dentro del ámbito de administración.

400 Solicitud incorrecta

  • Causa: parámetro no compatible o con formato incorrecto.
  • Corrección:
    • Compruebe los detalles del cmdlet para ver la combinación de punto de conexión y cmdlet.
    • Incluya solo los parámetros admitidos por el cmdlet en el punto de conexión REST.

Dirección URL base incorrecta

Problemas de paginación

  • Causa: cambiar parámetros entre llamadas paginadas o omitir @odata.nextLink.
  • Corrección:
    • Mantenga los parámetros coherentes en todas las páginas.
    • Siempre POST en la @odata.nextLink dirección URL.
    • Si no usa el parámetro ResultSize , la API tiene como valor predeterminado 1000 entradas por página.

Errores de enrutamiento

  • Causa: falta el encabezado X-AnchorMailbox o no es correcto para las operaciones con ámbito de buzón.
  • Corrección:
    • Incluya X-AnchorMailbox con el UPN del buzón (preferido) o la dirección SMTP.
    • Valide el valor antes de enviar la solicitud.

Procedimientos recomendados

Siga las instrucciones de esta sección para garantizar un uso confiable y eficaz de la API de Exchange Online Administración.

  • Autenticación y seguridad:

    • Use la autenticación de solo aplicación con certificados o identidades administradas para cargas de trabajo de producción.
    • Solicite solo los permisos que necesita (Exchange.ManageV2 o Exchange.ManageAsAppV2).
    • Asigne roles de RBAC mínimos para reducir el riesgo.

  • Diseño de la solicitud:

    • Use siempre POST para todas las operaciones, incluidos los cmdlets Get-* .
    • Incluya solo los parámetros admitidos para el cmdlet en el punto de conexión.
    • Use X-AnchorMailbox para todas las operaciones.

  • Optimización del rendimiento:

    • Use $select para reducir el tamaño de carga de respuesta.
    • Combine $select con la paginación de grandes conjuntos de datos.
    • Use el parámetro ResultSize . De lo contrario, la API tiene como valor predeterminado 1000 entradas por página.

  • Resistencia y control de errores:

    • Implemente la lógica de reintento para la limitación (HTTP 429) y respete Retry-After.
    • Identificadores de solicitud de registro de respuestas de error para la solución de problemas.
    • Valide los parámetros antes de enviar solicitudes para evitar 400 solicitudes incorrectas.

  • Enrutamiento y reconocimiento del entorno:

    • Use la dirección URL base correcta para su organización.
    • Incluya X-AnchorMailbox para todas las solicitudes para evitar errores de enrutamiento.

Pasos siguientes

  • Last updated on