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

Microsoft 365 Copilot Connectors bieten eine intuitive Möglichkeit, Ihre externen Daten in Microsoft Graph hinzuzufü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 den Abschnitt Copilot-Agents>und -Connectors des Microsoft 365 Admin Center anzeigen und verwalten.

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.

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

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:

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

   Hinweis: 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 Inhaltserfahrungen in Microsoft Search und Microsoft 365 Copilot aus.

Aktivitätseinstellungen

Aktivitätseinstellungen](/graph/api/resources/externalconnectors-activitysettings)Genehmigen Sie die URL-zu-ExternalItem-Zuordnungsmetadaten, mit denen Microsoft 365 erkennen kann, dass eine URL einem bestimmten indizierten Element in einer Copilot-Connectorverbindung entspricht.

• URL-Auflösung in Microsoft 365-Umgebungen

  • Wenn ein Benutzer eine URL in Microsoft 365-Umgebungen wie Microsoft Search oder Microsoft 365 Copilot sucht, einfüge oder freigibt, kann Microsoft 365 die konfigurierte urlToItemResolvers verwenden, um die URL in die entsprechende externalItemaufzulösen. Dadurch kann Microsoft 365 das durch die URL dargestellte indizierte Element identifizieren und erkannte Interaktionen dem richtigen externen Element zuordnen.

• Aktivitätssignal Mitschreiben über die Microsoft 365 Copilot-Erweiterung

  • Aktivitätssignale können mit der erweiterung Microsoft 365 Copilot erfasst werden, einer browserbasierten Erweiterung für Microsoft 365 Copilot. Wenn Aktivitätseinstellungen konfiguriert und die Erweiterung aktiviert ist, kann die Erweiterung automatisch Aktivitätssignale erfassen und mit indizierten Connectorelementen verknüpfen. Diese Signale tragen dazu bei, die Personalisierung und Relevanz in Microsoft 365 Copilot zu verbessern, indem Inhalte priorisiert werden, mit denen Benutzer in verbundenen Systemen interagieren.

Aktivitätseinstellungen stellen die URL-zu-Element-Zuordnung bereit, die erforderlich ist, damit diese Signale dem richtigen indizierten Element zugeordnet werden. 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.

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.

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.

Verwandte Inhalte

• Registrieren des Verbindungsschemas
• Lesen Sie die API-Referenz zu Copilot-Connectors.
• Herunterladen des Beispiel-Such-Connector von GitHub