Freigeben über

Aktivieren der vereinfachten Administratorumgebung für Ihren Microsoft Graph-Connector

  • Artikel

In diesem Artikel wird beschrieben, wie Sie die vereinfachte Administratorumgebung für Ihren Microsoft Graph-Connector im Teams Admin Center aktivieren. Wenn Sie diese Benutzeroberfläche aktivieren, können Teams-Administratoren Ihren benutzerdefinierten Microsoft Graph-Connector nahtlos im Teams Admin Center aktivieren oder deaktivieren.

Vereinfachte Administratorerfahrung im Teams Admin Center

So aktivieren Sie die vereinfachte Administratorerfahrung im Teams Admin Center:

  1. Aktualisieren Sie das Teams-App-Manifest.
  2. Aktualisieren von Microsoft Graph-Berechtigungen.
  3. Verarbeiten von Microsoft Graph-Webhookbenachrichtigungen.
  4. Erstellen oder Löschen von Microsoft Graph-Verbindungen
  5. Überprüfen Sie die Erfahrung, indem Sie den Microsoft Graph-Connector im Teams Admin Center aktivieren.

Aktualisieren des Teams-App-Manifests

Fügen Sie im Teams-App-Manifest im Stammverzeichnis auf der gleichen Ebene wie Eigenschaften wie Name, Beschreibung und Symbole die eigenschaft graphConnector (eingeführt in v1.11 des App-Manifests) mit einer notificationUrl hinzu. Dieses Feld enthält die URL, an die Microsoft Graph-Connectorbenachrichtigungen für die Anwendung gesendet werden. Die App-Manifestversion muss v1.13 oder höher sein, damit die vereinfachte Administratorumgebung funktioniert.

Stellen Sie sicher, dass die webApplicationInfo-Eigenschaft dem Manifest hinzugefügt wird. Nachdem Sie das Manifest aktualisiert haben, laden Sie es hoch, indem Sie die App querladen oder die App im Store veröffentlichen.

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

Aktualisieren von Microsoft Graph-Berechtigungen

  1. Wechseln Sie zu Microsoft Entra Admin Center.
  2. Erweitern Sie das Menü Identität, und wechseln Sie zu Anwendungen>App-Registrierungen.
  3. Wählen Sie Ihre App-Registrierung aus.
  4. Wechseln Sie zu API-Berechtigungen>Berechtigung>hinzufügen Microsoft Graph.
  5. Wählen Sie die ExternalConnection.ReadWrite.OwnedBy Microsoft Graph-Berechtigungen und ExternalItem.ReadWrite.OwnedBy aus, wie im folgenden Beispiel gezeigt.

Aktualisierte Microsoft Graph-Berechtigungen

Behandeln von Microsoft Graph-Webhookbenachrichtigungen

Wenn der Administrator den Microsoft Graph-Connector über das Teams Admin Center ein- oder ausschaltet , sendet Microsoft Graph eine Änderungsbenachrichtigung an die URL, die in der notificationUrl-Eigenschaft im Manifest angegeben ist. Ihre App muss diese Microsoft Graph-Verbindungen entsprechend verwalten.

Benachrichtigungen ändern

Weitere Informationen zum Einrichten von Änderungsbenachrichtigungen finden Sie unter Einrichten von Benachrichtigungen für Änderungen an Ressourcendaten. Das folgende Beispiel zeigt eine Nutzlast:

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

Informationen zum Überprüfen der eingehenden Änderungsbenachrichtigung finden Sie unter Überprüfen der Authentizität von Benachrichtigungen.

Beachten Sie die folgenden Tipps:

  • Sie können subscriptionExpirationDateTime und subscriptionId ignorieren.
  • Die Änderungsbenachrichtigung gilt nur für die Verwaltung des Microsoft Graph-Connectors, wenn die @odata.type der Ressourcendaten mit der in der Beispielnutzlast übereinstimmen.
  • Die identifizierte tenantId ist die Mandanten-ID des Kunden. Wenn Sie die Microsoft Graph-API aufrufen, um Microsoft Graph-Verbindungen zu verwalten, müssen Sie das App-Token im Namen der Mandanten-ID dieses Kunden generieren.
  • Sie können den Microsoft-Graph-API aufrufen, um den Anzeigenamen und den Standarddomänennamen des Kunden abzurufen. Diese Informationen können Ihnen helfen, die tenantId dem eindeutigen Bezeichner in Ihrem System zuzuordnen. Weitere Informationen finden Sie unter Suchen nach Mandanteninformationen nach Mandanten-ID.
  • Verwenden Sie in resourceDatastate , um zu bestimmen, ob Verbindungen erstellt oder gelöscht werden sollen. Sie benötigen connectorsTicket , um die Verbindungen zu erstellen.

Behandeln der Benachrichtigung "Connector aktiviert"

So verarbeiten Sie Benachrichtigungen zum Aktivieren des Connectors:

  • Ermitteln Sie, welche Microsoft Graph-Verbindungen erstellt werden sollen (wie viele Verbindungen und welches Schema für jede Verbindung), indem Sie die Listen-API für externe Verbindungen verwenden, um alle Verbindungen abzufragen. Bestimmen Sie, ob alle Verbindungen von Grund auf neu erstellt, die Erstellung von Verbindungen fortgesetzt werden soll (im Resilienzfluss) oder ob kein Vorgang ausgeführt werden soll (wenn alle gewünschten Verbindungen bereits bereit sind ).
  • Die Verbindung wird im Entwurfszustand erstellt. Übergeben Sie die connectorsTicket undurchsichtige codierte Zeichenfolge an die VERBINDUNGSerstellungs-API im GraphConnectors-Ticket HTTP-Header.
  • Registrieren Sie das Schema.
  • Nach einer erfolgreichen Schemaerstellung oder -aktualisierung sollte die Verbindung den Status "Bereit " erreichen.

Behandeln der Benachrichtigung "Connector deaktivieren"

So behandeln Sie Benachrichtigungen zum Deaktivieren des Connectors:

  • Ermitteln Sie, welche Microsoft Graph-Verbindungen gelöscht werden sollen, indem Sie die Api für die Liste externer Verbindungen verwenden, um alle Verbindungen abzufragen.
  • Löschen Sie alle Verbindungen mithilfe der Lösch-API für externe Verbindungen.
  • Es wird empfohlen, resilienzlogik zu erstellen, um die gelöschte Verbindung erneut zu versuchen, um zu überprüfen, ob sie gelöscht wurde.

Anforderung

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

Antwort

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

Sie müssen einen 202 - Accepted status Code in Ihrer Antwort an Microsoft Graph senden. Wenn Microsoft Graph keinen 2xx-Klassencode empfängt, wird versucht, die Änderungsbenachrichtigung für etwa vier Stunden mehrmals zu veröffentlichen. Danach wird die Änderungsbenachrichtigung gelöscht und nicht zugestellt.

So überprüfen Sie die Echtheit eines validatonTokens:

  • Vergewissern Sie sich, dass das Token nicht abgelaufen ist.
  • Stellen Sie sicher, dass das Token nicht manipuliert wurde und vom Microsoft Identity Platform ausgestellt wurde.
  • Überprüfen Sie, ob der AppId-Anspruch im validationToken enthalten ist.
  • Vergewissern Sie sich, dass der aud-Anspruch im validationToken mit dem angegebenen "{{Teams-appid}}" identisch ist.

Weitere Informationen finden Sie unter Überprüfen der Echtheit von Benachrichtigungen.

Das folgende Beispiel zeigt ein Validierungstoken.

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

Erstellen oder Löschen von Microsoft Graph-Verbindungen

Sie müssen die connectorTickets von der Nutzlast senden, die Sie als GraphConnectors-Ticket Header erhalten haben, wenn Sie die Erstellung der Teams-App-Verbindung initiieren. Im folgenden Beispiel wird dieser Prozess veranschaulicht.

Anforderung

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

Hinweis

  • Sie müssen {{connectorId}} auf den Wert festlegen, der in der Benachrichtigung von Graph-Connectors angegeben wird, wenn Sie die Verbindung erstellen.
  • Sie sollten {{accessToken}} aus dem Microsoft Identity Platform für den Mandanten abrufen, der benachrichtigt wird.

Antwort

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

Hinweis

Verschiedene Microsoft 365-Umgebungen können für die erstellten Verbindungen aktiviert werden. Weitere Informationen finden Sie in der Übersicht über Microsoft Graph-Connectors.

Informationen zum Erfassen externer Elemente in einer funktionierenden Microsoft Graph-Verbindung finden Sie unter Erstellen, Aktualisieren und Löschen von Elementen, die von Ihrer Anwendung über Microsoft Graph-Connectors hinzugefügt wurden.

Überprüfen Sie die Erfahrung, indem Sie den Microsoft Graph-Connector im Teams Admin Center aktivieren.

So überprüfen Sie die Benutzeroberfläche:

  1. Melden Sie sich beim Teams Admin Center als Teams-Administrator oder globaler Administrator des Mandanten an.
  2. Wählen Sie in der linken Schiene das Blatt Apps verwalten aus.
  3. Wechseln Sie zu Ihrer Teams-Anwendung.
  4. Auf der Detailseite der Teams-App sehen Sie eine neue Registerkarte Graph-Connector , die es einem Administrator ermöglicht, den Microsoft Graph-Connector zu aktivieren oder zu deaktivieren.
  5. Wählen Sie die Umschaltfläche aus, um die Aktivierungs- oder Deaktivierungsbenachrichtigungen an den Benachrichtigungsendpunkt der App zu senden, wie durch die eigenschaft graphConnector.notificationUrl im App-Manifest angegeben.

Bereitstellen Ihres Microsoft Graph-Connectors für andere Organisationen im Teams Admin Center

Sie können Ihren Microsoft Graph-Connector als Teams-App gepackt, die über Microsoft 365 erweitert wurde, an Microsoft Partner Center übermitteln. Dadurch kann Microsoft Ihren Microsoft Graph-Connector überprüfen, damit andere Organisationen ihn im Microsoft Teams Admin Center ermitteln und bereitstellen können.

Sie können den Schritt-für-Schritt-Übermittlungsleitfaden verwenden, um zu erfahren, wie Sie Ihre App übermitteln. Stellen Sie sicher, dass Sie eine Teams-App auf der Registerkarte Microsoft 365 und Copilot in Marketplace-Angeboten übermitteln.

Sie müssen im Schritt Zusätzliche Zertifizierungsinformationen eine PDF-Datei einreichen. Microsoft verwendet die Informationen, die Sie in dieser PDF-Datei angeben, um sicherzustellen, dass Ihr Microsoft Graph-Connector in Microsoft 365 Copilot wie erwartet funktioniert. Ihre PDF-Datei muss die folgenden Abschnitte enthalten:

  • Testkonten, Lizenzschlüssel und Anmeldeinformationen
  • Benutzerdefinierter vertikaler Name
  • Semantische Bezeichnungen
  • Beispiel für Prompts
  • Verbindungsbeschreibung
  • Aktivitätseinstellungen

Testkonten, Lizenzschlüssel und Anmeldeinformationen

Erstellen Sie ein Benutzerkonto auf Ihrem Demomandanten, mit dem Microsoft Ihren Microsoft Graph-Connector überprüfen kann. Dies kann im Abschnitt Benutzer des Microsoft 365 Admin Center erfolgen. Stellen Sie sicher, dass dieses neue Benutzerkonto über eine Microsoft 365 Copilot-Lizenz verfügt.

Geben Sie in diesem Abschnitt der PDF-Datei die Anmeldeinformationen und alle anwendbaren Lizenzschlüssel für dieses neue Benutzerkonto an. Diese Informationen sind obligatorisch. Weitere Informationen zum Vorbereiten des Benutzerkontos für die Überprüfung finden Sie unter Bewährte Methoden für die Bereitstellung von Testnotizen.

Nachdem Microsoft Ihre App überprüft hat, können Sie den Zugriff auf das Benutzerkonto widerrufen.

Benutzerdefinierter vertikaler Name

Erstellen Sie eine benutzerdefinierte Vertikale, die nur Ergebnisse von Ihrem benutzerdefinierten Microsoft Graph-Connector zurückgibt. Führen Sie dies im Abschnitt Verticals der Registerkarte Anpassung des Search & Intelligence Portal aus. Geben Sie in diesem Abschnitt der PDF den Namen dieser benutzerdefinierten Vertikale an. Ein Name für die benutzerdefinierte Vertikale ist obligatorisch.

Semantische Bezeichnungen

Geben Sie im Abschnitt Semantische Bezeichnungen an, welche Eigenschaften aus Ihrem Verbindungsschema die titlesemantischen Bezeichnungen , urlund iconUrl aufweisen. Diese Schemazuordnung ist obligatorisch.

Beispiel für Prompts

Geben Sie im Abschnitt Beispiel Prompts zwei Beispieleingabeaufforderungen an, mit denen Microsoft Ihren Microsoft Graph-Connector in Microsoft 365 Copilot überprüfen kann. Diese Eingabeaufforderungen sollten mindestens eine partielle Übereinstimmung mit der title semantischen Bezeichnung enthalten. Diese Eingabeaufforderungen sind obligatorisch.

Verbindungsbeschreibung

Geben Sie im Abschnitt Verbindungsbeschreibung die description Eigenschaft für Ihre benutzerdefinierte Microsoft Graph-Verbindung an. Microsoft verwendet dies, um sicherzustellen, dass Ihre Microsoft Graph-Verbindung über eine umfassende Beschreibung für Microsoft 365 Copilot verfügt. Die Beschreibung ist optional.

Aktivitätseinstellungen

Geben Sie im Abschnitt Aktivitätseinstellungen die Aktivitätseinstellungen für Ihre Microsoft Graph-Verbindung mit einer Ressource an urlToItemResolvers . Die Aktivitätseinstellungen sind optional, es wird jedoch dringend empfohlen, sie anzugeben.