Compartir a través de

Habilitación de la experiencia de administración simplificada para el conector de Microsoft Graph

  • Artículo

En este artículo se describe cómo habilitar la experiencia de administración simplificada para el conector de Microsoft Graph en el Centro de administración de Teams. Al habilitar esta experiencia, los administradores de Teams pueden habilitar o deshabilitar el conector personalizado de Microsoft Graph sin problemas en el Centro de administración de Teams.

Experiencia de administración simplificada en el Centro de administración de Teams

Para habilitar la experiencia de administración simplificada en el Centro de administración de Teams:

  1. Actualice el manifiesto de aplicación de Teams.
  2. Actualice los permisos de Microsoft Graph.
  3. Controle las notificaciones de webhook de Microsoft Graph.
  4. Cree o elimine conexiones de Microsoft Graph.
  5. Valide la experiencia habilitando El conector de Microsoft Graph en el Centro de administración de Teams.

Actualización del manifiesto de aplicación de Teams

En el manifiesto de aplicación de Teams, en la raíz, en el mismo nivel que las propiedades como nombre, descripción e iconos, agregue la propiedad graphConnector (introducida en la versión 1.11 del manifiesto de la aplicación) con notificationUrl. Este campo contiene la dirección URL a la que se envían las notificaciones del conector de Microsoft Graph para la aplicación. La versión del manifiesto de la aplicación debe ser v1.13 o posterior para que funcione la experiencia de administración simplificada.

Asegúrese de que la propiedad webApplicationInfo se agrega al manifiesto. Después de actualizar el manifiesto, cárguelo mediante la instalación local de la aplicación o la publicación de la aplicación en la tienda.

{
 "$schema":"https://developer.microsoft.com/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
  "manifestVersion": "1.13",
  ...
  "webApplicationInfo": {
    "id": "<AAD_APP_ID>",  // e.g. "7e47846e-4bef-4c42-9817-a14e92287f28"
    "resource": "<AAD_APP_RESOURCE>" // e.g. "api://xmngc.loca.lt/7e47846e-4bef-4c42-9817-a14e92287f28"

  },
  "graphConnector": {
    "notificationUrl": "<AAD_APP_NOTIFICATION_URL>"
  }
}

Actualización de permisos de Microsoft Graph

  1. Ve a Centro de administración Microsoft Entra.
  2. Expanda el menú Identidad y vaya a Aplicaciones>Registros de aplicaciones.
  3. Seleccione el registro de la aplicación.
  4. Vaya a Permisos> de APIAgregar un permiso>Microsoft Graph.
  5. Seleccione los ExternalConnection.ReadWrite.OwnedBy permisos y ExternalItem.ReadWrite.OwnedBy Microsoft Graph como se muestra en el ejemplo siguiente.

Permisos actualizados de Microsoft Graph

Control de notificaciones de webhook de Microsoft Graph

Cuando el administrador activa o desactiva el conector de Microsoft Graph desde el Centro de administración de Teams, Microsoft Graph envía una notificación de cambio a la dirección URL especificada en la propiedad notificationUrl del manifiesto. La aplicación debe administrar estas conexiones de Microsoft Graph en consecuencia.

Notificaciones de cambios

Para obtener más información sobre cómo configurar notificaciones de cambios, consulte Configuración de notificaciones para cambios en los datos de recursos. En el ejemplo siguiente se muestra una carga:

{
  "validationTokens": [
    "[jwt validation token]"
  ],
  "value": [
    {
      "changeType": "updated",
      "clientState": null,
      "resource": "external",
      "resourceData": {
        "@odata.id": "external",
        "id": "[graph connector id]",
        "state": "enabled", // or disabled
        "connectorsTicket": "[An opaque encoded string]",
        "@odata.type": "#Microsoft.Graph.connector"
      },
      "subscriptionExpirationDateTime": "2024-08-30T13:01:48.3441108-07:00",
      "subscriptionId": "[change notification's subscription id]",
      "tenantId": "[customer's tenant id]"
    }
  ]
}

Para comprender cómo validar la notificación de cambio entrante, consulte Validación de la autenticidad de las notificaciones.

Tenga en cuenta lo siguiente:

  • Puede omitir subscriptionExpirationDateTime y subscriptionId.
  • La notificación de cambio es para la administración del conector de Microsoft Graph solo cuando el @odata.type de los datos del recurso coincide con el de la carga de ejemplo.
  • El tenantId identificado es el identificador de inquilino del cliente. Al llamar a Microsoft Graph API para administrar las conexiones de Microsoft Graph, debe generar el token de aplicación en nombre del identificador de inquilino de este cliente.
  • Puede llamar al Graph API de Microsoft para obtener el nombre para mostrar del cliente y el nombre de dominio predeterminado. Esta información puede ayudarle a asignar tenantId al identificador único del sistema. Para obtener más información, consulte Búsqueda de información de inquilino por identificador de inquilino.
  • En resourceData, use state para determinar si desea crear o eliminar conexiones. Necesita el conectorsTicket para crear las conexiones.

Control de la notificación de "habilitación del conector"

Para controlar las notificaciones de "habilitación del conector":

  • Determine qué conexiones de Microsoft Graph se van a crear (cuántas conexiones y qué esquema para cada conexión) mediante la API de lista de conexiones externas para consultar todas las conexiones. Determine si desea crear todas las conexiones desde cero, reanudar la creación de conexiones (en flujo de resistencia) o sin operación (cuando todas las conexiones deseadas ya están en estado listo ).
  • La conexión se crea en un estado de borrador . Pase la connectorsTicket cadena codificada opaca a la API de creación de conexiones en el GraphConnectors-Ticket encabezado HTTP.
  • Registre el esquema.
  • Después de crear o actualizar correctamente el esquema, la conexión debe alcanzar un estado listo .

Control de la notificación de "deshabilitación del conector"

Para controlar las notificaciones de "deshabilitación del conector":

Solicitud

POST https://example.com/notificationEndpoint
Content-type: application/json
Content-length: 100

{
  "value": [
    {
      "changeType": "updated",
      "subscriptionId": "79f3b611-7f15-4bdd-9422-9606a24e49f3",
      "resource": "external",
      "clientState": null,
      "resourceData": {
        "@odata.type": "#Microsoft.Graph.connector",
        "@odata.id": "external",
        "id": "{{connectorId}}",
        "state": "enabled" //e.g. enabled or disabled
        "connectorsTicket":"eyJhbGciOiJIUzI1…"
      },
      "subscriptionExpirationDateTime": "2021-06-26T12:40:26.4436785-07:00",
      "tenantId": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93"
    }
  ],
  "validationTokens": [ "eyJ0eXAiOiJKV…" ]
}

Respuesta

HTTP/1.1 202 Accepted
Content-type: application/json
Content-length: 0

Debe enviar un 202 - Accepted código de estado en la respuesta a Microsoft Graph. Si Microsoft Graph no recibe un código de clase 2xx, intenta publicar la notificación de cambio varias veces durante aproximadamente cuatro horas. Después de eso, la notificación de cambio se quita y no se entrega.

Para validar la autenticidad de un validatonToken:

  • Compruebe que el token no ha expirado.
  • Compruebe que el token no se ha alterado y que el Plataforma de identidad de Microsoft lo emitió.
  • Compruebe que la notificación appId en validationToken.
  • Compruebe que la notificación aud en validationToken es la misma que la "{{Teams-appid}}" que especificó.

Para obtener más información, consulte Validación de la autenticidad de la notificación.

En el ejemplo siguiente se muestra un token de validación.

{ "typ": "JWT", "alg": "RS256", "x5t": "nOo3ZDrODXEK1jKWhXslHR_KXEg", "kid": "nOo3ZDrODXEK1jKWhXslHR_KXEg" }.{ "aud": "e478830d-8f49-4c26-80c6-58f68e0f064b", "iss": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "iat": 1624649764, "nbf": 1624649764, "exp": 1624736464, "aio": "E2ZgYGjnuFglnX7mtjJzwR5lYaWvAA==", "appid": "0bf30f3b-4a52-48df-9a82-234910c4a086", "appidacr": "2", "idp": "https://sts.windows.net/9f4ebab6-520d-49c0-85cc-7b25c78d4a93/", "oid": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "rh": "0.AX0AtrpOnw1SwEmFzHslx41KkzsP8wtSSt9ImoIjSRDEoIZ9AAA.", "sub": "1e7d79fa-7893-4d50-bdde-164260d9c5ba", "tid": "9f4ebab6-520d-49c0-85cc-7b25c78d4a93", "uti": "mIB4QKCeZE6hK71XUHJ3AA", "ver": "1.0" }.[Signature]

Creación o eliminación de conexiones de Microsoft Graph

Debe enviar el connectorTickets desde la carga que recibió como GraphConnectors-Ticket encabezado al iniciar la creación de la conexión de la aplicación de Teams. En el ejemplo siguiente se muestra este proceso.

Solicitud

POST https://graph.microsoft.com/v1.0/external/connection
GraphConnectors-Ticket: {{connectorsTicket}}
Content-type: application/json
Authorization: bearer {{accessToken}}

{
    "id": "{{connectionId}}",
    "name": "Contoso HR",
    "description": "Connection to index Contoso HR system",
    "connectorId": "{{connectorId}}",
    "enabledContentExperiences": "MicrosoftSearch, Compliance, …",
    "searchSettings": { … },
    "complianceSettings": { … },
    …
}

Nota:

  • Debe establecer {{connectorId}} en el valor proporcionado en la notificación de Graph Connectors al crear la conexión.
  • Debe adquirir {{accessToken}} del Plataforma de identidad de Microsoft para el inquilino al que se notifica.

Respuesta

HTTP/1.1 200 Accepted
Content-type: application/json
Content-length: 0

Nota:

Se pueden habilitar varias experiencias de Microsoft 365 para las conexiones creadas. Para obtener más información, consulte Información general de la conectores de Microsoft Graph.

Para obtener información sobre cómo ingerir elementos externos en una conexión de Microsoft Graph en funcionamiento, consulte Creación, actualización y eliminación de elementos agregados por la aplicación a través de conectores de Microsoft Graph.

Validar la experiencia habilitando el conector de Microsoft Graph en el Centro de administración de Teams

Para validar la experiencia:

  1. Inicie sesión en el Centro de administración de Teams como administrador de Teams o administrador global del inquilino.
  2. Seleccione la hoja Administrar aplicaciones en el carril izquierdo.
  3. Vaya a la aplicación de Teams.
  4. En la página de detalles de la aplicación Teams, verá una nueva pestaña conector de Graph que permite a un administrador habilitar o deshabilitar el conector de Microsoft Graph.
  5. Seleccione el botón de alternancia para enviar las notificaciones de habilitación o deshabilitación al punto de conexión de notificación de la aplicación, tal como especifica la propiedad graphConnector.notificationUrl en el manifiesto de la aplicación.

Hacer que el conector de Microsoft Graph esté disponible para otras organizaciones en el Centro de administración de Teams

Puede enviar el conector de Microsoft Graph empaquetado como una aplicación de Teams extendida en Microsoft 365 al Centro de partners de Microsoft. Esto permite a Microsoft validar el conector de Microsoft Graph para que otras organizaciones puedan detectarlo e implementarlo en el Centro de administración de Microsoft Teams.

Puede usar la guía de envío paso a paso para aprender a enviar la aplicación. Asegúrese de enviar una aplicación de Teams en la pestaña Microsoft 365 y Copilot en ofertas de Marketplace.

Debe enviar un PDF en el paso Información de certificación adicional . Microsoft usa la información que proporciona en este PDF para asegurarse de que el conector de Microsoft Graph funciona según lo esperado en Microsoft 365 Copilot. El PDF debe tener las secciones siguientes:

  • Cuentas de prueba, claves de licencia y credenciales
  • Nombre vertical personalizado
  • Etiquetas semánticas
  • Consultas de ejemplo
  • Descripción de la conexión
  • Configuración de actividad

Cuentas de prueba, claves de licencia y credenciales

Cree una cuenta de usuario en el inquilino de demostración que Microsoft puede usar para validar el conector de Microsoft Graph. Esto se puede hacer en la sección Usuarios del Centro de Administración de Microsoft 365. Asegúrese de que esta nueva cuenta de usuario tiene una licencia de Microsoft 365 Copilot.

En esta sección del PDF, proporcione las credenciales y las claves de licencia aplicables para esta nueva cuenta de usuario. Esta información es obligatoria. Para obtener más información sobre cómo preparar la cuenta de usuario para la validación, consulte procedimientos recomendados para proporcionar notas de prueba.

Una vez que Microsoft valida la aplicación, puede revocar el acceso a la cuenta de usuario.

Nombre vertical personalizado

Cree un vertical personalizado que solo devuelva los resultados del conector personalizado de Microsoft Graph. Haga esto en la sección Verticales de la pestaña Personalización del Portal de búsqueda de inteligencia de &. En esta sección del PDF, proporcione el nombre de esta vertical personalizada. Un nombre para el vertical personalizado es obligatorio.

Etiquetas semánticas

En la sección Etiquetas semánticas, indique qué propiedades del esquema de conexión tienen las titleetiquetas semánticas , urly iconUrl . Esta asignación de esquema es obligatoria.

Consultas de ejemplo

En la sección Consultas de ejemplo, proporcione dos mensajes de ejemplo que Microsoft puede usar para validar el conector de Microsoft Graph en Microsoft 365 Copilot. Estas solicitudes deben incluir al menos una coincidencia parcial con la title etiqueta semántica. Estos avisos son obligatorios.

Descripción de la conexión

En la sección Descripción de la conexión, proporcione la propiedad para la description conexión personalizada de Microsoft Graph. Microsoft usa esto para asegurarse de que la conexión de Microsoft Graph tiene una descripción enriquecida para Microsoft 365 Copilot. Esta descripción es opcional.

Configuración de actividad

En la sección Configuración de actividad, proporcione la configuración de actividad para la conexión de Microsoft Graph con un urlToItemResolvers recurso. La configuración de la actividad es opcional, pero se recomienda encarecidamente proporcionarlas.