Konfigurieren einer externen Verbindung und Bereitstellen eines Schemas

Abgeschlossen

In dieser Lerneinheit erfahren Sie, wie Sie eine Microsoft Entra-App-Registrierung für die Verwendung mit einem benutzerdefinierten Graph-Connector konfigurieren. Außerdem erfahren Sie, wie Sie eine externe Verbindung erstellen und ein Schema zum Importieren externer Inhalte konfigurieren.

Konfigurieren Microsoft Entra App-Registrierung

Um externe Inhalte in Microsoft 365 zu importieren, benötigt ein Graph-Connector eine externe Verbindung und ein Schema. Ein benutzerdefinierter Graph-Connector verwendet Microsoft Graph-APIs, um die externe Verbindung zu erstellen und das Schema bereitzustellen. Für die Kommunikation mit Graph-APIs wird die Authentifizierung bei Microsoft 365 mithilfe einer Microsoft Entra App-Registrierung durchgeführt. In der Regel handelt es sich bei Graph-Connectors um Apps, die ohne Benutzerinteraktion ausgeführt werden. Damit Connectors die Verbindung erstellen, das Schema bereitstellen und externe Inhalte erfassen können, gewähren Sie ihnen die folgenden Anwendungsberechtigungen:

• ExternalConnection.ReadWrite.OwnedBy – ermöglicht es dem Connector, die Verbindung zu erstellen und das Schema bereitzustellen.
• ExternalItem.ReadWrite.OwnedBy – ermöglicht dem Connector die Erfassung externer Elemente

Beide Berechtigungen ermöglichen es dem Connector, nur auf die Verbindung und die Elemente zuzugreifen, die er besitzt. Dies ist die empfohlene Sicherheitsmethode.

Erstellen einer externen Verbindung

Ein benutzerdefinierter Graph-Connector erstellt mithilfe des Microsoft Graph-Endpunkts externe Verbindung eine externe Verbindung. Beim Erstellen einer Verbindung müssen Sie die ID, den Namen und die Beschreibung angeben. Die ID muss in Ihrem Microsoft 365-Mandanten eindeutig sein und zwischen 3 und 32 Zeichen lang sein. Der folgende Codeausschnitt zeigt, wie eine externe Verbindung erstellt wird:

using Microsoft.Graph.Models.ExternalConnectors;

var requestBody = new ExternalConnection
{
  Id = "msgraphdocs",
  Name = "Microsoft Graph documentation",
  Description = "Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.",
};

await graphClient.External.Connections.PostAsync(requestBody);

Bereitstellen des Schemas

Nachdem Sie eine externe Verbindung erstellt haben, besteht der nächste Schritt darin, das Schema bereitzustellen. Das Schema besteht aus einer oder mehreren Eigenschaften. Für jede Eigenschaft müssen Sie den Namen und den Typ der gespeicherten Daten angeben. Sie können auch definieren, ob die zugehörigen Daten für die Volltextsuche und -sortierung verwendet werden sollen. Schließlich können Sie eine oder mehrere semantische Bezeichnungen hinzufügen, die Microsoft 365 dabei helfen zu verstehen, welche Informationen die Eigenschaft darstellt. Microsoft 365 Copilot erfordert eine externe Verbindung, um in ihrem Schema mindestens die semantischen Bezeichnungen title, url und iconUrl zu definieren. Der folgende Codeausschnitt zeigt, wie Sie ein Schema bereitstellen:

using Microsoft.Graph.Models.ExternalConnectors;

var schema = new Schema
{
  BaseType = "microsoft.graph.externalItem",
  Properties = new()
  {
    new Property
    {
      Name = "title",
      Type = PropertyType.String,
      IsQueryable = true,
      IsSearchable = true,
      IsRetrievable = true,
      Labels = new() { Label.Title }
    },
    new Property
    {
      Name = "iconUrl",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.IconUrl }
    },
    new Property
    {
      Name = "url",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.Url }
    },
  }
};

await graphClient.External
  .Connections["{externalConnection-id}"]
  .Schema
  .PatchAsync(schema);

Die Bereitstellung eines externen Verbindungsschemas ist ein zeitintensiver Vorgang, der zwischen 5 und 15 Minuten dauert. Wenn Sie wissen möchten, wann die Bereitstellung abgeschlossen ist und die Verbindung einsatzbereit ist, rufen Sie Informationen zur Verbindung ab, und überprüfen Sie deren status. Wenn die Verbindung noch nicht bereit ist, warten Sie 1 Minute, bevor Sie die status erneut überprüfen.

do {
  var externalConnection = await GraphService.Client.External
    .Connections["{externalConnection-id}"]
    .GetAsync();

  if (externalConnection?.State != ConnectionState.Draft)
  {
    break;
  }

  await Task.Delay(60_000);
}
while (true);