Acceso al teléfono de Teams sin pasar por el cliente de Teams

Importante

Esta característica de Azure Communication Services se encuentra actualmente en versión preliminar. Las características de la versión preliminar están disponibles públicamente y se pueden usar en todos los clientes nuevos y existentes de Microsoft.

Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que las funcionalidades estén restringidas.

Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

En este artículo se describe cómo conceder consentimiento a un servidor para recibir llamadas dirigidas a una cuenta de recursos de Teams. En las secciones siguientes también se describe cómo usar un cliente para responder y realizar llamadas en nombre de las cuentas de recursos de Teams.

Prerrequisitos

• Una cuenta de Azure con una suscripción activa. Crear una cuenta gratuita.

• Un recurso de Communication Services, vea Crear un recurso de Communication Services.

• Un inquilino de Microsoft Entra ID con usuarios que tengan una licencia de Teams. Para obtener más información, consulte Requisitos de licencia de Teams.

• Los usuarios deben estar habilitados para Teams. Para habilitar un usuario para Teams, abra el Centro > de administración de Microsoft 365 Usuarios>activos. A continuación, busque la cuenta de usuario afectada. Haga clic en Editar para cambiar sus detalles. Vaya a Licencia y aplicaciones y, a continuación, seleccione la flecha desplegable de Aplicaciones y seleccione Habilitar Microsoft Teams.

Proporcionar consentimiento del servidor

El propietario del recurso de Azure Communication Services debe ejecutar las siguientes operaciones de API. El propietario del recurso debe proporcionar consentimiento para autorizar las llamadas al recurso de Azure Communication Services desde la cuenta de recursos de Teams. Puede llamar a la API mediante cualquier herramienta REST o mediante programación. La API admite operaciones GET, PUT, PATCH y DELETE.

1. El {YOUR-ACS-RESOURCE-ENDPOINT} en la ruta de acceso del URI de solicitud (RURI) es el nombre de dominio completo (FQDN) del recurso de Azure Communication Services desde Azure.
2. El {YOUR-RESOURCE-ACCOUNT-GUID} parámetro en la RURI es el valor oid devuelto por el Graph API desde el paso anterior. Como alternativa, para un aprovisionamiento manual único, el cmdlet Get-CsOnlineApplicationInstance (MicrosoftTeamsPowerShell) devuelve el ObjectId y ese identificador es el YOUR-RESOURCE-ACCOUNT-GUID.
3. El {TENANT-GUID} en la ruta de acceso de RURI es el GUID de inquilino de Teams.
4. El {principalType} en el cuerpo es teamsResourceAccount porque estamos aceptando una cuenta de recursos de Teams para la extensibilidad del Teléfono Teams.

Esta API admite el código de autenticación de mensajes basado en hash (HMAC) de Azure Communication Services con una cadena de conexión o una identidad administrada de Microsoft Entra ID.

Definición de consulta:

https://{YOUR-ACS-RESOURCE-ENDPOINT}/access/teamsExtension/tenants/{TENANT-GUID}/assignments/{YOUR-RESOURCE-ACCOUNT-GUID}?api-version=2025-03-02-preview 

Ejemplo para establecer el consentimiento:

PUT https://myacsresource.unitedstates.communication.azure.com/access/teamsExtension/tenants/zz123456-1234-1234-1234-zzz123456789/assignments/cc123456-5678-5678-1234-ccc123456789?api-version=2025-03-02-preview

{
   "principalType": "teamsResourceAccount"
}

Respuesta de ejemplo:

HTTP/1.1 201 Created
Content-type: application/json

Respuesta no permitida:

Si recibe un error 403 con la siguiente respuesta, envíe el GUID de suscripción de Azure al Administrador de productos (PM) de Azure Communication Services para agregarle a la lista de vista previa.

{
   "error": {
   "code": "SubscriptionNotAllowed",
   "message": "API is not allowed to be accessed with your subscription."
}
}

Proporcionar consentimiento del cliente

Use el SDK de llamadas de Azure Communication Services para ampliar el sistema telefónico de Teams, lo que permite realizar y recibir llamadas independientemente de la aplicación teams.

Configuración de la aplicación

Paso 1: Crear o seleccionar un registro de aplicación de Microsoft Entra ID

Los usuarios deben autenticarse a través de una aplicación de Microsoft Entra ID con el permiso de Azure Communication Service TeamsExtension.ManageCalls. Si no tiene una aplicación existente para este inicio rápido, puede crear un nuevo registro de aplicación.

Configure la siguiente configuración de aplicación:

• La propiedad Tipos de cuenta admitidos define si la aplicación es de un solo inquilino (solo cuentas en este directorio organizativo) o multiinquilino (cuentas en cualquier directorio organizativo). Elija la opción que se adapte a su escenario.

• El URI de redirección define el URI donde se redirige la solicitud de autenticación después de la autenticación. En nuestro escenario de aplicación web, elija Aplicación de página única y escriba http://localhost como URI.

Para obtener información más detallada, consulte Registro de una aplicación con la plataforma de identidad de Microsoft.

Cuando se registra la aplicación, busque el identificador en la información general. Usa el ID de aplicación (cliente) en los siguientes pasos.

Paso 2: Agregar el TeamsExtension.ManageCalls permiso a la aplicación

Debe registrar la aplicación para permiso TeamsExtension.ManageCalls de la aplicación Azure Communication Services. Necesita este permiso para que el usuario de Teams acceda a los flujos de extensibilidad de Teams Phone a través de Azure Communication Services.

1. Vaya a la aplicación Microsoft Entra ID en Azure Portal y seleccione Permisos de API.

2. Seleccione Agregar permisos.

3. En el menú Agregar permisos , seleccione Azure Communication Services.

4. Seleccione el permiso TeamsExtension.ManageCallsy, a continuación, seleccione Agregar permisos.

   

5. Conceda el consentimiento del administrador para el permiso TeamsExtension.ManageCalls.

Concesión de acceso de un usuario de Teams al recurso de Azure Communication Services

Envíe una solicitud a la API de asignaciones de acceso telefónico de Microsoft Teams para conceder a un usuario de Teams acceso a través del recurso de Communication Services. Para obtener más información sobre cómo autenticar la solicitud web, consulte Autenticación.

En el ejemplo siguiente se muestra una solicitud de un usuario con identificador e5b7f628-ea94-4fdc-b3d9-1af1fe231111.

PUT {endpoint}/access/teamsExtension/tenants/87d349ed-44d7-43e1-9a83-5f2406dee5bd/assignments/e5b7f628-ea94-4fdc-b3d9-1af1fe231111?api-version=2025-03-02-preview

{
    "principalType" : "user",
    "clientIds" : ["1bfa671a-dc6b-47f3-8940-45c0f1af0fa6"]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 201 Created
Content-type: application/json

{
    "objectId": "e5b7f628-ea94-4fdc-b3d9-1af1fe231111",
    "tenantId": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
    "principalType" : "user",
    "clientIds" : ["1bfa671a-dc6b-47f3-8940-45c0f1af0fa6"]
}

Flujo de inicio de sesión

Complete esta sección para configurar un flujo de inicio de sesión para la aplicación.

Creación de una credencial capaz de obtener un token de usuario de Microsoft Entra

Para crear una credencial, use el SDK @azure/communication-common con la versión 2.3.2-beta.1. En primer lugar, debe inicializar cualquier implementación de la interfaz TokenCredential y proporcionarla a EntraCommunicationTokenCredentialOptions.

Junto con el token, debe proporcionar el URI del recurso de Azure Communication Services y los permisos necesarios para el token de usuario de Microsoft Entra. Estos ámbitos determinan los permisos concedidos al token:

const entraTokenCredential = new InteractiveBrowserCredential({
  tenantId: "<your-tenant-id>",
  clientId: "<your-client-id>",
  redirectUri: "<your-redirect-uri>",
});

const entraTokenCredentialOptions = {
  resourceEndpoint: "https://<your-resource>.communication.azure.com",
  tokenCredential: entraTokenCredential,
  scopes: [
    "https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls",
  ],
};

const credential = new AzureCommunicationTokenCredential(
  entraTokenCredentialOptions
);

Introduzca AzureCommunicationUserCredential en CallClient.CreateCallAgent

Una vez que tenga lista la credencial, puede pasarla a CallingClient.

const client = new CallingClient();
const callAgent = await client.createCallAgent(credential);

Eliminación del acceso de usuario de Teams

Envíe una solicitud a la API de asignaciones de acceso telefónico de Microsoft Teams para eliminar el acceso del usuario de Teams al recurso de Azure Communication Services.

DELETE {endpoint}/access/teamsExtension/tenants/87d349ed-44d7-43e1-9a83-5f2406dee5bd/assignments/e5b7f628-ea94-4fdc-b3d9-1af1fe231111?api-version=2025-03-02-preview

Respuesta

HTTP/1.1 204 NoContent
Content-type: application/json

{}

Para comprobar que el usuario de Teams ya no está vinculado con el recurso de Communication Services, envíe una solicitud GET a la API de asignaciones de acceso telefónico de Microsoft Teams. Compruebe que su código de estado de respuesta es 404.

GET {endpoint}/access/teamsExtension/tenants/87d349ed-44d7-43e1-9a83-5f2406dee5bd/assignments/e5b7f628-ea94-4fdc-b3d9-1af1fe231111?api-version=2025-03-02-preview

Pasos siguientes

API REST para la extensibilidad del teléfono de Teams

Artículos relacionados

• Descripción general de la extensibilidad de Teams Phone
• Inicio rápido de extensibilidad del sistema telefónico de Teams