Erstellen, Aktualisieren und Löschen von Verbindungen in Microsoft Graph

Artikel
12/21/2023

Die Microsoft Graph Connectors-Plattform bietet eine intuitive Möglichkeit, Ihre externen Daten in Microsoft Graph einzufügen. Eine Verbindung ist ein logischer Container für Ihre externen Daten, den ein Administrator als eine Einheit verwalten kann.

Nachdem eine Verbindung hergestellt wurde, können Sie Ihre Inhalte aus einer beliebigen externen Datenquelle hinzufügen, z. B. aus einer lokalen Inhaltsquelle oder einem externen SaaS-Dienst (Software-as-a-Service). Sie können nur die Verbindungen anzeigen und verwalten, die Sie angelegt haben oder zu deren Verwaltung Sie explizit autorisiert wurden. Ein Suchadministrator kann alle Verbindungen im Mandanten über das Modern Admin Center anzeigen und verwalten.

Beispiel für die Struktur des benutzerdefinierten Helpdesksystems Tickets Connector.

Beispiel für ein benutzerdefiniertes Helpdesk-System einer Tickets-Connector-Struktur.

Administrator-Ansicht von Verbindungen einschließlich des benutzerdefinierten Ticket-Connectors.

Administrator-Ansicht von Verbindungen einschließlich des benutzerdefinierten Ticket-Connectors.

Sie können eine Verbindung beliebig modellieren, aber das häufigste Modell ist das Erstellen einer Verbindung für jede Instanz Ihres Connectors. Beispielsweise wird jedes Mal, wenn Sie den Microsoft Windows-Dateifreigabe-Connector einrichten, eine neue Verbindung erstellt. Sie können auch eine einzige Verbindung erstellen, um alle Elemente aus Ihrer Datenquelle hinzuzufügen. Beispielsweise können Sie eine einzige Verbindung erstellen, um alle Tickets und Vorfälle für mehrere Teams aus Ihrem Helpdesk-System hinzuzufügen.

Status und Vorgänge

Ihre Verbindung kann in einem der folgenden Status existieren.

Status	Beschreibung
Entwurf	Eine leere Verbindung wird bereitgestellt. Keine der Datenquellen, Schemas oder Einstellungen ist konfiguriert.
Bereit	Die Verbindung wird mit dem registrierten Schema bereitgestellt und ist zur Erfassung bereit.
Veraltet	Dies geschieht, wenn ein abhängiges Feature, z. B. eine API, veraltet ist. Das Löschen der Verbindung ist der einzige zulässige Vorgang.
LimitExceeded	Wenn Sie das maximale Limit einer einzelnen Verbindung oder das Kontingent auf Mandantenebene für alle Verbindungen erreichen, können Sie erst dann weitere Elemente hinzufügen, wenn Sie den Status beenden.

In der folgenden Tabelle sind die verfügbaren Vorgänge in den einzelnen Status angegeben.

Vorgang	Entwurf	Bereit	Veraltet	LimitExceeded
Verbindung erstellen	❌	✔️	❌	✔️
Verbindung lesen	✔️	✔️	✔️	✔️
Verbindung aktualisieren	✔️	✔️	❌	✔️
Verbindung löschen	✔️	✔️	✔️	✔️
Schema erstellen	✔️	❌	❌	❌
Schema lesen	❌	✔️	✔️	✔️
Schema aktualisieren	❌	❌	❌	❌
Schema löschen	❌	❌	❌	❌
Element erstellen	❌	✔️	❌	❌
Element lesen	❌	✔️	✔️	✔️
Element aktualisieren	❌	✔️	❌	✔️
Element löschen	❌	✔️	❌	✔️

Eine Verbindung ermöglicht es Ihrer Anwendung, ein Schema zu definieren für Elemente, die indiziert werden sollen, und stellt einen Endpunkt für Ihren Dienst zum Hinzufügen, Aktualisieren oder Löschen von Elementen im Index bereit.

Das Erstellen einer Verbindung ist der erste Schritt, damit eine Anwendung Elemente zum Suchindex hinzufügen kann.

Erstellen einer Verbindung

Bevor eine Anwendung dem Suchindex Elemente hinzufügen kann, muss eine Verbindung erstellt und konfiguriert werden:

Erstellen Sie eine Verbindung mit einem eindeutigen Bezeichner, einem Anzeigenamen und einer Beschreibung.
Registrieren Sie ein Schema, um die Felder zu definieren, die im Index enthalten sein sollen.

Anmerkung: Weitere Informationen zum Aktualisieren des Schemas für eine vorhandene Verbindung finden Sie unter Schemaupdatefunktionen.

Verbindungseinstellungen

Sie können die Standardverbindungseinstellungen für jede aktivierte Inhaltsumgebung konfigurieren. Wenn diese Einstellungen aktiviert sind, wirken sich diese Einstellungen auf die Inhaltserfahrung aus.

Sucheinstellungen

Sie können definieren, wie Suchergebnisse auf der Microsoft Search-Ergebnisseite angezeigt werden, indem Sie die standardmäßigen Suchanzeigevorlagen für Ihre Inhalte in searchSettings angeben. Eine Gruppe von Suchanzeigevorlagen kann verwendet werden, um verschiedene Arten von Suchergebnissen unterschiedlich anzuzeigen. Eine Suchanzeigevorlage verfügt über ein Ergebnislayout, das mit adaptiven Karten und Regeln erstellt wurde, die eine oder mehrere Bedingungen angeben. Wenn diese Bedingungen erfüllt sind, wird das Layout auf das Suchergebnis angewendet und auf der Ergebnisseite angezeigt.

Aktivitätseinstellungen

In Den Aktivitätseinstellungen können Sie Microsoft 365-Apps eine Möglichkeit bieten, Freigabeaktivitäten zu erkennen, wodurch Ihre Inhalte Benutzern empfohlen werden können, die am meisten mit diesen Inhalten interagieren. Fügen Sie dazu einen urlToItemResolver hinzu. Dadurch kann eine URL aus der in Microsoft 365-Apps erkannten Verbindung in die entsprechende Element-ID im externalItem aufgelöst werden.

Die folgende Abbildung zeigt, wie Ihr Element in Der Empfehlungserfahrung in Microsoft 365 angezeigt werden kann.

Das folgende Beispiel zeigt die activitySettings-Nutzlast mit einem vollständigen urlToItemResolvers-Abschnitt . Wenn beispielsweise jemand den Link https://contoso.com/items/39483948/freigibt, stellt dies ein externalItem dar, das über eine Microsoft Graph-Verbindung erfasst wurde. In diesem Beispiel stellt der freigegebene Link ein externalItem-Objekt mit einer itemId von id_39483948dar. Diese Verbindung gibt an, wie die URL der itemId dieses externalItem zugeordnet werden soll. In diesem Beispiel weist diese Verbindung die ID auf contosohr.

Aktualisieren Sie die Aktivitätseinstellungen, indem Sie eine Patchanforderung für die Verbindung senden.

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

Die folgende activitySettings-Nutzlast wird mit der Patchanforderung gesendet.

{
  "@odata.type": "#microsoft.graph.externalConnectors.activitySettings",
  "urlToItemResolvers": [
    {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
          "itemId": "id_{myItemId}",  
          "priority": 1,
          "urlMatchInfo": {
            "@odata.type": "microsoft.graph.externalConnectors.urlMatchInfo",
            "baseUrls": [
              "https://contoso.com"
            ],
            "urlPattern": "/items/(?<myItemId>[0-9]+)"
          }
    }
  ]
}

In diesem Beispiel wurde im Feld itemId angegeben, wie die ID des externen Elements erstellt werden soll, das die URL darstellt. Auf die itemId wird in urlPattern (innerhalb von urlMatchInfo) verwiesen, um als ID des externalItem zu extrahieren39483948.

Sie können eine Liste von bis zu acht itemIdResolver-Ressourcen in der urlToItemResolvers-Ressource für die Nutzlast Ihrer Aktivitätseinstellungen angeben. Geben Sie für jede dieser urlMatchInfo-Ressourcen den Wert #microsoft.graph.externalConnectors.itemIdResolver für @odata.type, eine ganze Zahl von 1 bis acht für die priority-Eigenschaft und ein urlMatchInfo-Objekt an, das eine Liste von Basis-URLs und einen regulären Ausdruck enthält.

Wenn ein Link freigegeben wird, werden die urlMatchInfo-Objekte , die zu den Resolvern gehören, in der Reihenfolge angewendet, in der die Prioritätswerte angegeben sind. In aufsteigender Prioritätsreihenfolge wird die URL zuerst mit den URLs in der BaseUrls-Liste in der urlMatchInfo-Eigenschaft verglichen. Wenn sich dann die Basis der Link-URL in der baseUrls-Liste befindet, wird der reguläre Ausdruck urlPattern auf die URL angewendet. Wenn dieses Muster übereinstimmt, werden keine weiteren Resolver angewendet. Wenn die Basis der Link-URL nicht in der baseUrls-Liste enthalten ist oder urlPattern nicht übereinstimmt, wird der nächste urlToItemResolver ausgewertet, bis eine Übereinstimmung gefunden wird oder keine urltoItemResolver-Ressourcen mehr angewendet werden müssen.

Weitere Informationen zu urlMatchInfo-Ressourcen finden Sie unter urlMatchInfo-Typ.

Aktualisieren einer Verbindung

Um den Anzeigenamen, die Beschreibung oder die aktivierten Inhaltsfunktionen für eine vorhandene Verbindung zu ändern, können Sie die Verbindung aktualisieren.

Löschen einer Verbindung

Um alle Elemente zu entfernen, die über eine Verbindung indiziert wurden, können Sie eine Verbindung löschen.

Teilen über