Partager via

Activer l’expérience d’administration simplifiée pour votre connecteur Microsoft Graph

  • Article

Cet article explique comment activer l’expérience d’administration simplifiée pour votre connecteur Microsoft Graph dans le Centre d’administration Teams. Lorsque vous activez cette expérience, les administrateurs Teams peuvent activer ou désactiver votre connecteur Microsoft Graph personnalisé en toute transparence dans le Centre d’administration Teams.

Expérience d’administration simplifiée dans le Centre d’administration Teams

Pour activer l’expérience d’administration simplifiée dans le Centre d’administration Teams :

  1. Mettez à jour le manifeste de l’application Teams.
  2. Mettre à jour les autorisations Microsoft Graph.
  3. Gérer les notifications de webhook Microsoft Graph.
  4. Créer ou supprimer des connexions Microsoft Graph.
  5. Validez l’expérience en activant le connecteur Microsoft Graph dans le Centre d’administration Teams.

Mettre à jour le manifeste de l’application Teams

Dans le manifeste de l’application Teams, à la racine, au même niveau que les propriétés telles que le nom, la description et les icônes, ajoutez la propriété graphConnector (introduite dans la version 1.11 du manifeste de l’application) avec une notificationUrl. Ce champ contient l’URL à laquelle les notifications de connecteur Microsoft Graph pour l’application sont envoyées. La version du manifeste d’application doit être v1.13 ou ultérieure pour que l’expérience d’administration simplifiée fonctionne.

Vérifiez que la propriété webApplicationInfo est ajoutée au manifeste. Après avoir mis à jour le manifeste, chargez-le en chargeant l’application ou en la publiant dans le Store.

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

Mettre à jour les autorisations Microsoft Graph

  1. Allez à centre d’administration Microsoft Entra.
  2. Développez le menu Identité et accédez à Applications>inscriptions d'applications.
  3. Sélectionnez votre inscription d’application.
  4. Accédez à Autorisations> d’APIAjouter une autorisation>Microsoft Graph.
  5. Sélectionnez les ExternalConnection.ReadWrite.OwnedBy autorisations et ExternalItem.ReadWrite.OwnedBy Microsoft Graph comme indiqué dans l’exemple suivant.

Autorisations Microsoft Graph mises à jour

Gérer les notifications de webhook Microsoft Graph

Lorsque l’administrateur active ou désactive le connecteur Microsoft Graph à partir du Centre d’administration Teams, Microsoft Graph envoie une notification de modification à l’URL spécifiée dans la propriété notificationUrl dans le manifeste. Votre application doit gérer ces connexions Microsoft Graph en conséquence.

Notifications de modification

Pour plus d’informations sur la configuration des notifications de modification, consultez Configurer des notifications pour les modifications apportées aux données de ressources. L’exemple suivant montre une charge utile :

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

Pour comprendre comment valider la notification de modification entrante, consultez Validation de l’authenticité des notifications.

Gardez à l’esprit les conseils suivants :

  • Vous pouvez ignorer subscriptionExpirationDateTime et subscriptionId.
  • La notification de modification est destinée à la gestion du connecteur Microsoft Graph uniquement lorsque le @odata.type des données de ressource correspond à celui de l’exemple de charge utile.
  • Le tenantId identifié est l’ID de locataire du client. Lorsque vous appelez microsoft API Graph pour gérer les connexions Microsoft Graph, vous devez générer le jeton d’application au nom de l’ID de locataire de ce client.
  • Vous pouvez appeler le API Graph Microsoft pour obtenir le nom d’affichage et le nom de domaine par défaut du client. Ces informations peuvent vous aider à mapper le tenantId à l’identificateur unique dans votre système. Pour plus d’informations, consultez Rechercher des informations sur le locataire par ID de locataire.
  • Dans resourceData, utilisez l’état pour déterminer s’il faut créer ou supprimer des connexions. Vous avez besoin des connecteursTicket pour créer les connexions.

Gestion de la notification « activation du connecteur »

Pour gérer les notifications « activer le connecteur » :

  • Déterminez les connexions Microsoft Graph à créer (le nombre de connexions et le schéma de chaque connexion) à l’aide de l’API Liste de connexions externes pour interroger toutes les connexions. Déterminez s’il faut créer toutes les connexions à partir de zéro, reprendre la création des connexions (dans le flux de résilience) ou sans opération (lorsque toutes les connexions souhaitées sont déjà à l’état prêt ).
  • La connexion est créée dans un état brouillon . Passez la connectorsTicket chaîne opaque encodée à l’API de création de connexion dans l’en-tête GraphConnectors-Ticket HTTP.
  • Inscrivez le schéma.
  • Après la création ou la mise à jour du schéma, la connexion doit atteindre un état prêt .

Gestion de la notification « désactivation du connecteur »

Pour gérer les notifications de « désactivation du connecteur » :

Demande

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

Réponse

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

Vous devez envoyer un 202 - Accepted code status dans votre réponse à Microsoft Graph. Si Microsoft Graph ne reçoit pas de code de classe 2xx, il tente de publier la notification de modification plusieurs fois pendant environ quatre heures. Après cela, la notification de modification est supprimée et n’est pas remise.

Pour valider l’authenticité d’un validateonToken :

  • Vérifiez que le jeton n’a pas expiré.
  • Vérifiez que le jeton n’a pas été falsifié et qu’il a été émis par le Plateforme d'identités Microsoft.
  • Vérifiez que la revendication appId dans validationToken.
  • Vérifiez que la revendication aud dans validationToken est identique à la revendication « {{Teams-appid}} » que vous avez spécifiée.

Pour plus d’informations, consultez Validation de l’authenticité de la notification.

L’exemple suivant montre un jeton de validation.

{ "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]

Créer ou supprimer des connexions Microsoft Graph

Vous devez envoyer les connectorTickets à partir de la charge utile que vous avez reçue en tant qu’en-tête GraphConnectors-Ticket lorsque vous lancez la création de la connexion d’application Teams. L’exemple suivant illustre ce processus.

Demande

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": { … },
    …
}

Remarque

  • Vous devez définir {{connectorId}} sur la valeur fournie dans la notification des connecteurs Graph lorsque vous créez la connexion.
  • Vous devez acquérir le {{accessToken}} à partir du Plateforme d'identités Microsoft pour le locataire qui est notifié.

Réponse

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

Remarque

Différentes expériences Microsoft 365 peuvent être activées pour les connexions créées. Pour plus d’informations, consultez Vue d'ensemble des connecteurs Microsoft Graph.

Pour savoir comment ingérer des éléments externes dans une connexion Microsoft Graph opérationnelle, consultez Créer, mettre à jour et supprimer des éléments ajoutés par votre application via des connecteurs Microsoft Graph.

Valider l’expérience en activant le connecteur Microsoft Graph dans le Centre d’administration Teams

Pour valider l’expérience :

  1. Connectez-vous au Centre d’administration Teams en tant qu’administrateur Teams ou administrateur général du locataire.
  2. Sélectionnez le panneau Gérer les applications dans le rail gauche.
  3. Accédez à votre application Teams.
  4. Dans la page de détails de l’application Teams, vous remarquez un nouvel onglet Connecteur Graph qui permet à un administrateur d’activer ou de désactiver le connecteur Microsoft Graph.
  5. Sélectionnez le bouton bascule pour envoyer les notifications d’activation ou de désactivation au point de terminaison de notification de l’application, comme spécifié par la propriété graphConnector.notificationUrl dans le manifeste de l’application.

Rendre votre connecteur Microsoft Graph disponible pour d’autres organisations dans le Centre d’administration Teams

Vous pouvez envoyer votre connecteur Microsoft Graph empaqueté en tant qu’application Teams étendue dans Microsoft 365 à l’Espace partenaires Microsoft. Cela permet à Microsoft de valider votre connecteur Microsoft Graph, afin que d’autres organisations puissent le découvrir et le déployer dans le Centre d’administration Microsoft Teams.

Vous pouvez utiliser le guide de soumission pas à pas pour découvrir comment soumettre votre application. Veillez à envoyer une application Teams sous l’onglet Microsoft 365 et Copilot des offres de la Place de marché.

Vous devez envoyer un fichier PDF à l’étape Informations de certification supplémentaires . Microsoft utilise les informations que vous fournissez dans ce fichier PDF pour s’assurer que votre connecteur Microsoft Graph fonctionne comme prévu dans Microsoft 365 Copilot. Votre fichier PDF doit comporter les sections suivantes :

  • Tester les comptes, les clés de licence et les informations d’identification
  • Nom vertical personnalisé
  • Étiquettes sémantiques
  • Exemple de Requêtes
  • Description de la connexion
  • Paramètres d’activité

Tester les comptes, les clés de licence et les informations d’identification

Créez un compte d’utilisateur sur votre locataire de démonstration que Microsoft peut utiliser pour valider votre connecteur Microsoft Graph. Cette opération peut être effectuée dans la section Utilisateurs du Centre Administration Microsoft 365. Vérifiez que ce nouveau compte d’utilisateur dispose d’une licence Microsoft 365 Copilot.

Dans cette section du fichier PDF, fournissez les informations d’identification et toutes les clés de licence applicables pour ce nouveau compte d’utilisateur. Ces informations sont obligatoires. Pour en savoir plus sur la préparation du compte d’utilisateur à la validation, consultez les meilleures pratiques pour fournir des notes de test.

Une fois que Microsoft a validé votre application, vous pouvez révoquer l’accès au compte d’utilisateur.

Nom vertical personnalisé

Créez un vertical personnalisé qui retourne uniquement les résultats de votre connecteur Microsoft Graph personnalisé. Pour ce faire, accédez à la section Verticals de l’onglet Personnalisation du portail Rechercher & Intelligence. Dans cette section du fichier PDF, indiquez le nom de ce vertical personnalisé. Un nom pour le vertical personnalisé est obligatoire.

Étiquettes sémantiques

Dans la section Étiquettes sémantiques, indiquez quelles propriétés de votre schéma de connexion ont les titleétiquettes sémantiques , urlet iconUrl . Ce mappage de schéma est obligatoire.

Exemple de Requêtes

Dans la section Exemple Requêtes, fournissez deux exemples d’invites que Microsoft peut utiliser pour valider votre connecteur Microsoft Graph dans Microsoft 365 Copilot. Ces invites doivent inclure au moins une correspondance partielle avec l’étiquette title sémantique. Ces invites sont obligatoires.

Description de la connexion

Dans la section Description de la connexion, indiquez la description propriété de votre connexion Microsoft Graph personnalisée. Microsoft l’utilise pour s’assurer que votre connexion Microsoft Graph a une description détaillée pour Microsoft 365 Copilot. Cette description est facultative.

Paramètres d’activité

Dans la section Paramètres de l’activité, fournissez les paramètres d’activité de votre connexion Microsoft Graph avec une urlToItemResolvers ressource. Les paramètres d’activité sont facultatifs, mais nous vous recommandons vivement de les fournir.