Übung: Konfigurieren einer externen Verbindung und Bereitstellen eines Schemas

8 Minuten

In dieser Übung erstellen Sie einen benutzerdefinierten Microsoft Graph-Connector als Konsolenanwendung. Sie registrieren eine neue Microsoft Entra App-Registrierung und fügen den Code hinzu, um eine externe Verbindung zu erstellen und das zugehörige Schema bereitzustellen.

Erstellen eines neuen Graph-Connectorprojekts

Erstellen Sie zunächst ein neues Graph-Connectorprojekt. Während Sie das Projekt und alle erforderlichen Dateien manuell erstellen könnten, verwenden Sie in diesem Beispiel das GitHub-Vorlagenrepository für Graph-Connectors. Der Vorteil der Verwendung des Vorlagenrepositorys besteht darin, dass es ein einfaches Projekt für Sie mit den erforderlichen Dateien und Abhängigkeiten erstellt, wodurch Sie Zeit sparen.

In einer Befehlszeile:

Klonen Des Vorlagenrepositorys durch Ausführen von git clone https://github.com/microsoft/learn-microsoft-graph-connectors-dotnet.git

Tipp

Wenn Git nicht installiert ist oder kein GitHub-Konto vorhanden ist, können Sie das Repository als ZIP-Datei herunterladen. Extrahieren Sie die ZIP-Datei in einen Ordner auf Ihrem Computer, um mit der Übung fortzufahren.
Ändern Sie das Arbeitsverzeichnis in das geklonte Repository.
Öffnen Sie das neu erstellte Projekt in Ihrem Code-Editor.

Innerhalb des Code-Editors:

Öffnen Sie die ConnectionConfiguration.cs Datei. In dem vom ExternalConnection Getter zurückgegebenen Objekt:
1. Ändern Sie den Wert der Id-Eigenschaft in msgraphdocs.
2. Ändern Sie den Wert der Name-Eigenschaft in Microsoft Graph documentation.
3. Ändern Sie den Wert der Description-Eigenschaft in Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.
Speichern Sie Ihre Änderungen.

Tipp

Die README.md Datei im generierten Projekt enthält weitere Informationen zu den verschiedenen Dateien und Ordnern im Projekt. Nehmen Sie sich einen Moment Zeit, um es zu lesen und sich mit der Projektstruktur vertraut zu machen.

Registrieren einer neuen Microsoft Entra-App-Registrierung

Das von Ihnen erstellte Projekt enthält ein Setupskript, das eine neue Microsoft Entra App-Registrierung erstellt und konfiguriert. Der Graph-Connector verwendet diese App-Registrierung, um sich bei Microsoft 365 zu authentifizieren.

In einer Befehlszeile:

Ändern Sie das Arbeitsverzeichnis in den Projektordner.
Führen Sie das Setupskript aus: .\setup.ps1
Melden Sie sich bei Ihrem Microsoft 365-Mandanten mit Ihrem Geschäftskonto an, wenn Sie dazu aufgefordert werden.
Warten Sie, bis das Skript die Erstellung der App-Registrierung abgeschlossen hat. Das Skript erstellt eine Entra-App-Registrierung mit dem Namen Microsoft Graph-Dokumentation.
Nach Abschluss des Skripts werden die App-Registrierungsinformationen sicher in benutzergeheimnissen Gespeichert.

Das Setupskript verwendet das Microsoft Graph PowerShell SDK, um eine neue Microsoft Entra App-Registrierung in Ihrem Mandanten zu erstellen. Es konfiguriert die App-Registrierung bei Microsoft Graph-API Berechtigungen, die zum Erstellen einer externen Verbindung und zum Erfassen von Inhalten erforderlich sind. Außerdem wird die App-Registrierung mit einem Geheimnis konfiguriert, um die Authentifizierung ohne Benutzerinteraktion zu ermöglichen.

Tipp

So erkunden Sie die Konfiguration der App-Registrierung in einem Webbrowser:

Wechseln Sie zum Azure-Portal unter https://portal.azure.com.
Wählen Sie im Navigationsbereich Microsoft Entra ID aus.
Wählen Sie im seitenseitigen Navigationsbereich App-Registrierungen aus.
Wählen Sie in der Liste der App-Registrierungen die app-Registrierung aus, die vom Setupskript erstellt wurde.
Erkunden Sie die verschiedenen Eigenschaften, z. B . API-Berechtigungen, Zertifikate & Geheimnisse und Authentifizierung.

Definieren der externen Verbindung und der Schemakonfiguration

Der nächste Schritt besteht darin, die externe Verbindung und das Schema zu definieren, die der Graph-Connector verwenden soll. Da der Code des Connectors an mehreren Stellen Zugriff auf die ID der externen Verbindung benötigt, speichern Sie sie an einer zentralen Stelle in Ihrem Code.

Innerhalb des Code-Editors:

Öffnen Sie die ConnectionConfiguration.cs Datei.
Entfernen Sie aus dem von der ExternalConnection -Eigenschaft zurückgegebenen -Objekt die ActivitySettings Eigenschaften und SearchSettings . Sie benötigen sie für diese Übung nicht.
Beachten Sie die von der Schema -Eigenschaft zurückgegebenen Schemaeigenschaften.

Die erste Eigenschaft ist title, die den Titel des in Microsoft 365 importierten externen Elements speichert. Der Titel des Elements ist Teil des Volltextindexes (IsSearchable = true). Benutzer können den Inhalt auch explizit in Schlüsselwort (keyword) Abfragen (IsQueryable = true) abfragen. Der Titel kann auch abgerufen und in Suchergebnissen angezeigt werden (IsRetrievable = true). Die title -Eigenschaft stellt den Titel des Elements dar, den Sie mithilfe der Title semantischen Bezeichnung angeben.

Als Nächstes gibt es die url -Eigenschaft, die die ursprüngliche URL des externen Elements speichert. Benutzer verwenden diese URL, um aus den Suchergebnissen oder Copilot von Microsoft 365 zum externen Element zu navigieren. URL ist eine der Eigenschaften, die Microsoft 365 Copilot erfordert, weshalb Sie sie mithilfe der Url semantischen Bezeichnung zuordnen.

Schließlich gibt es die iconUrl -Eigenschaft, die die URL des Symbols für jedes Element speichert. Microsoft 365 Copilot erfordert diese Eigenschaft und muss mithilfe der IconUrl semantischen Bezeichnung zugeordnet werden.

Microsoft 365 Copilot erfordert, dass Graph-Connectors mindestens diese drei Eigenschaften definieren und mit den entsprechenden semantischen Bezeichnungen festlegen.
Fügen Sie dem Properties Array eine neue Eigenschaft mit dem Namen hinzu description:
```
new Property
{
  Name = "description",
  Type = PropertyType.String,
  IsQueryable = true,
  IsSearchable = true,
  IsRetrievable = true
}
```
Die description -Eigenschaft speichert die Zusammenfassung des Inhalts des externen Elements. Die Definition ähnelt dem Titel. Es gibt jedoch keine semantische Bezeichnung für die Beschreibung, weshalb Sie sie nicht definieren.

Der vollständige Code sieht wie folgt aus:

using System.Text.Json;
using Microsoft.Graph.Models;
using Microsoft.Graph.Models.ExternalConnectors;

static class ConnectionConfiguration
{
  private static Dictionary<string, object>? _layout;
  private static Dictionary<string, object> Layout
  {
    get
    {
      if (_layout is null)
      {
        var adaptiveCard = File.ReadAllText("resultLayout.json");
        _layout = JsonSerializer.Deserialize<Dictionary<string, object>>(adaptiveCard);
      }

      return _layout!;
    }
  }

  public static ExternalConnection ExternalConnection
  {
    get
    {
      return 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."
      };
    }
  }

  public static Schema Schema
  {
    get
    {
      return 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 = "url",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.Url }
          },
          new Property
          {
            Name = "iconUrl",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.IconUrl }
          },
          new Property
          {
            Name = "description",
            Type = PropertyType.String,
            IsQueryable = true,
            IsSearchable = true,
            IsRetrievable = true
          }
        }
      };
    }
  }
}

Save your changes

Überprüfen des Verbindungserstellungscodes

Der Graph-Connectorprojekt-Generator erstellt Code, der die externe Verbindung erstellt und ihr Schema bereitstellt. Sie können es ohne Änderungen verwenden. Bevor Sie dies tun, sehen Sie sich es an, um zu verstehen, wie es funktioniert. Der Code befindet sich in der ConnectionService.cs-Datei .

Innerhalb des Code-Editors:

Öffnen Sie die datei ConnectionService.cs .
Die Datei enthält zwei Methoden: CreateConnection und CreateSchema. Die CreateConnection -Methode erstellt die externe Verbindung, und die CreateSchema -Methode stellt das Schema fest.

Wenn Sie sich erinnern, ist die Bereitstellung eines externen Verbindungsschemas ein zeitintensiver Vorgang. Der Code in der CreateSchema -Methode wartet jedoch anscheinend nicht auf die Bereitstellung des Schemas. Der Microsoft Graph-Client in diesem Projekt verwendet eine benutzerdefinierte Middleware, die auf den Abschluss des Vorgangs wartet. Da diese Middleware das Warten auf den Abschluss des Vorgangs verarbeitet, muss die CreateSchema Funktion keinen anderen Code enthalten und muss nur auf die API-Anforderung warten. Die Middleware befindet sich in der CompleteJobWithDelayHandler.cs-Datei .

Testen des Codes

Der letzte schritt besteht darin, zu überprüfen, ob der Code ordnungsgemäß funktioniert. Die Program.cs-Datei enthält den Einstiegspunkt für die Anwendung. Es verwendet das System.CommandLine-Paket , um einen Befehl zu definieren, den Sie aufrufen, indem Sie die Anwendung über die Befehlszeile starten.

In einer Befehlszeile:

Öffnen Sie ein Terminal.
Ändern Sie das Arbeitsverzeichnis in den Projektordner.
Führen Sie aus dotnet build , um das Projekt zu erstellen.
Starten Sie die App, indem Sie ausführen dotnet run -- create-connection.
Warten Sie einige Minuten, bis die Verbindung und das Schema erstellt wurden.

Übung: Konfigurieren einer externen Verbindung und Bereitstellen eines Schemas

Erstellen eines neuen Graph-Connectorprojekts

Registrieren einer neuen Microsoft Entra-App-Registrierung

Definieren der externen Verbindung und der Schemakonfiguration

Überprüfen des Verbindungserstellungscodes

Testen des Codes

Feedback