Bewährte Methoden für das Sdk für Microsoft Graph-Connectors

  • Artikel

Dieser Artikel enthält bewährte Methoden, die Sie befolgen sollten, wenn Sie das Microsoft Graph Connectors SDK verwenden, um einen benutzerdefinierten Connector zu implementieren.

Verwenden der Durchforstungsstatusmarkierung

Die Durchforstungsstatusmarkierung fungiert als Bezeichner für das bestimmte Element, das vom Connector gesendet wurde, das zuletzt von der Plattform verarbeitet wurde. Sie können zwei Arten von Durchforstungen implementieren: regelmäßige vollständige und inkrementelle.

Regelmäßige vollständige Durchforstungen rufen alle Elemente in der Datenquelle ab und erfassen nur die Elemente, die geändert wurden oder nicht im Index vorhanden sind. Wenn ein Element nicht gefunden wird, wird es aus dem Index gelöscht.

Bei inkrementellen Durchforstungen werden Elemente abgerufen, die seit der letzten inkrementellen Durchforstung hinzugefügt oder geändert wurden. Der Connector kann auch Elemente senden, die im Rahmen dieser Durchforstung gelöscht werden sollen. Für die erste inkrementelle Durchforstung wird auch die Startzeit der letzten vollständigen Durchforstung gesendet. Der Connector kann diese Durchforstung optional verwenden, um Elemente abzurufen, die erst nach der letzten vollständigen Durchforstung geändert wurden.

Sowohl regelmäßige vollständige als auch inkrementelle Durchforstungen verfügen über ihre Durchforstungsfortschrittsmarkierungen.

Verwendung der Durchforstungsstatusmarkierung während regelmäßiger vollständiger Durchforstungen

Das SDK sendet die Durchforstungsstatusmarkierung, wenn die vorherige Durchforstung abgestürzt ist oder eine geplante Durchforstung verpasst wurde, da der Microsoft Graph-Connector-Agent während regelmäßiger vollständiger Durchforstungen offline ist.

Wenn die vorherige Durchforstung nicht abstürzt, müssen Sie die Datenquelle von Anfang an durchforsten.

Verwendung der Durchforstungsstatusmarkierung während inkrementeller Durchforstungen

Während einer inkrementellen Durchforstung sendet der Connector die Durchforstungsstatusmarkierung an die Connectorplattform. Dies wird auch für die nächsten inkrementellen Durchforstungen ausgeführt. Der Connector kann diese Durchforstung verwenden, um nach diesem Marker hinzugefügte oder geänderte Elemente abzurufen.

Erstellen generischer Typen

Die Eigenschaftswerte des Inhaltselements können einen Bereich von Datentypen aufweisen. Da gRPC kein Konstrukt für generische Objekte enthält, enthält das SDK eine GenericType-Struktur , die einen der unterstützten Datentypen enthalten kann. GenericType weist die folgende Struktur auf:

// Represents a generic type that can hold any supported value
message GenericType {
 // Value of the Generic type
 oneof value {
  // String type value
  string stringValue = 1;

  // Long value
  int64 intValue = 2;


  // Double value
  double doubleValue = 3;

  // DateTime value
  google.protobuf.Timestamp dateTimeValue = 4;

  // Boolean value
  bool boolValue = 5;

  // String collection value
  StringCollectionType stringCollectionValue = 6;

  // Long collection value
  IntCollectionType intCollectionValue = 7;

  // Double collection value
  DoubleCollectionType doubleCollectionValue = 8;

  // DateTime collection value
  TimestampCollectionType dateTimeCollectionValue = 9;
 }
}

// Collection of string
message StringCollectionType {
 // Value of string collection
 repeated string values = 1;
}

// Collection of long
message IntCollectionType {
 // Value of long collection
 repeated int64 values = 1;
}

// Collection of double
message DoubleCollectionType {
 // Value of double collection
 repeated double values = 1;
}

// Collection of DateTime
message TimestampCollectionType {
 // Value of DateTime collection
 repeated google.protobuf.Timestamp values = 1;
}

GenericType kann einen der folgenden Typen aufweisen: string, int64, double, DateTime und Boolean oder eine Auflistung von string, int64, double und DateTime. Im Folgenden finden Sie Beispiele für das Festlegen dieser Typen:

// Setting string value in generic type
    GenericType stringType = new GenericType
    {
        StringValue = "Hello"
    };

    // Setting int64 value in generic type
    GenericType int64Type = new GenericType
    {
        IntValue = 1000
    };

    // Setting double value in generic type
    GenericType doubleType = new GenericType
    {
        DoubleValue = 12.54
    };

    // Setting dateTime value in generic type
    GenericType dateTimeType = new GenericType
    {
        DateTimeValue = Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(DateTime.UtcNow)
    };

    // Setting boolean value in generic type
    GenericType boolType = new GenericType
    {
        BoolValue = true
    };

    // Setting string collection value in generic type - Initialize the string collection first, add the values to the string collection and then set it in the generic type
    StringCollectionType stringCollection = new StringCollectionType();
    stringCollection.Values.Add("Value1");
    stringCollection.Values.Add("Value2");
    GenericType stringCollectionType = new GenericType
    {
        StringCollectionValue = stringCollection
    };

    // Setting int64 collection value in generic type - Initialize the int64 collection first, add the values to the int64 collection and then set it in the generic type
    IntCollectionType intCollection = new IntCollectionType();
    intCollection.Values.Add(1234);
    intCollection.Values.Add(5436);
    GenericType intCollectionType = new GenericType
    {
        IntCollectionValue = intCollection
    };

    // Setting double collection value in generic type - Initialize the double collection first, add the values to the double collection and then set it in the generic type
    DoubleCollectionType doubleCollection = new DoubleCollectionType();
    doubleCollection.Values.Add(12.54);
    doubleCollection.Values.Add(34.213);
    GenericType doubleCollectionType = new GenericType
    {
        DoubleCollectionValue = doubleCollection
    };

    // Setting datetime collection value in generic type - Initialize the datetime collection first, add the values to the datetime collection and then set it in the generic type
    TimestampCollectionType dateTimeCollection = new TimestampCollectionType();
    dateTimeCollection.Values.Add(Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(DateTime.UtcNow));
    dateTimeCollection.Values.Add(Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(DateTime.UtcNow.AddDays(-1)));
    GenericType dateTimeCollectionType = new GenericType
    {
        DateTimeCollectionValue = dateTimeCollection
    };

Erstellen eines Suchschemas

Für das Connectorsschema gelten die folgenden Einschränkungen:

  • Eigenschaftsname: Der Name der Eigenschaft darf maximal 32 Zeichen enthalten, und es sind nur alphanumerische Zeichen zulässig.
  • Search Anmerkungen:
    • Nur Eigenschaften vom Typ String oder StringCollection können durchsucht werden.
    • Nur Eigenschaften vom Typ String können eine Inhaltseigenschaft sein.
    • Inhaltseigenschaften müssen durchsuchbar sein.
    • Inhaltseigenschaften können nicht abfragbar oder abrufbar sein.
    • Die einschränkungsfähige Eigenschaft sollte nicht durchsuchbar sein.
    • Die einschränkungsfähige Eigenschaft sollte abfragbar und abrufbar sein.
    • Boolesche Eigenschaften können nicht eingeschränkt werden.
  • Aliase: Ein Satz von Aliasen oder ein Anzeigename für die Eigenschaft kann maximal 32 Zeichen enthalten, und nur alphanumerische Zeichen sind zulässig.

Abrufen von Elementen während einer Durchforstung

Die GetCrawlStream-Methode ist eine Serverstreamingmethode. Jedes Element aus der Datenquelle wird während der Durchforstung in ein CrawlStreamBit konvertiert und über den Antwortstream gesendet.

Um einen guten Durchsatz zu erzielen, sollte der Connector einen Batch von Elementen aus der Datenquelle abrufen, jedes Element in CrawlStreamBit konvertieren und sie über den Antwortstream senden. Die Batchgröße hängt von der Datenquelle ab. Wir empfehlen 25 als optimale Größe, um einen kontinuierlichen Fluss von Elementen über den Stream aufrechtzuerhalten.

Ausnahmebehandlung im Connectorcode

Alle Antworten der gRPC-Aufrufe verfügen über einen OperationStatus , der angibt, ob der Vorgang erfolgreich war oder fehlgeschlagen ist, die Ursache des Fehlers und Wiederholungsdetails, wenn Fehler vorliegen. Es wird empfohlen, den gesamten Code in einen try-catch-Block einzuschließen. Der Connector sollte alle Ausnahmen protokollieren und einen ordnungsgemäßen Vorgang status an die Plattform senden.

Verbindungsverwaltungsflows senden eine Antwort mit der StatusMessage, die im Microsoft 365 Admin Center angezeigt wird. Das Senden aussagekräftiger Meldungen erleichtert das Debuggen der Fehler auf der Benutzeroberfläche und vermeidet nicht behandelte Ausnahmen.

Timeouts

Alle Methoden in ConnectionManagementService sollten innerhalb von 30 Sekunden abgeschlossen und zurückgegeben werden. Andernfalls gibt die Plattform eine Timeoutfehlermeldung für die Anforderung zurück.

Zurücksenden von Fehlern vom Connector an die Plattform

Alle Antworten verwenden operationStatus in der Antwortstruktur. Wenn Fehler aufgetreten sind, sollten die Connectors OperationStatus verwenden, um die Fehlerursache zu senden und die Informationen an die Plattform zu wiederholen. Verwenden Sie OperationStatus , um die Fehler bei Durchforstungen festzulegen, wenn Fehler auf Verbindungsebene wie abgelaufene Anmeldeinformationen für den Zugriff auf die Datenquelle auftreten.

Die OperationStatus-Struktur verfügt über drei Felder, die zur Darstellung beliebiger Fehler verwendet werden können.

OperationResult

OperationResult ist eine Enumeration, die den Fehlergrund enthalten kann.

StatusMessage

StatusMessage ist eine Eigenschaft von OperationStatus , die die benutzerdefinierte Nachricht speichern kann, um die Fehlerursache anzuzeigen, die dem Administrator während der Verbindungseinrichtung angezeigt wird. Wenn die Anmeldeinformationen beispielsweise während der Überprüfung mit der ValidateAuthentication-Methode falsch sind, kann die Result-Eigenschaft auf AuthenticationIssue und die statusMessage-Eigenschaft auf Falsche Anmeldeinformationen angegeben festgelegt werden. Wenn die ValidateAuthentication-Methode aufgerufen wird, wird diese statusMessage dem Suchadministrator angezeigt. Bei Durchforstungen wird in diesem Szenario die Verbindung in den Fehlerzustand versetzt, der Authentifizierungsfehler wird dem Administrator angezeigt, und der Administrator wird aufgefordert, die Anmeldeinformationen für den Zugriff auf die Datenquelle zu aktualisieren.

RetryDetails

RetryDetails ermöglicht es dem Connector, Informationen zu vorübergehenden Fehlern während der Durchforstungen erneut an die Plattform zu senden und sie zum Wiederholen des Vorgangs zu verwenden.

Der Wiederholungsversuch kann ein Standardmäßiges oder exponentielles Backoff sein. Der Connector kann die Pausenzeit, die Backoffrate und den Backoff-Koeffizient festlegen und zurücksenden. Wenn die Datenquelle beispielsweise während der Durchforstung gedrosselt wird, kann der Connector OperationResult auf DatasourceError festlegen und die Wiederholungsdetails entsprechend dem Wiederholungsheader in den Antwortheadern der Datenquelle senden.

Fehlerzuordnung für OperationResult

Die folgenden Fehler versetzen die Verbindung in den Fehlerzustand:

  • OperationResult.AuthenticationIssue

  • OperationResult.ValidationFailure

Die anderen Vorgangscodes werden als vorübergehende Fehler behandelt und in nachfolgenden Durchforstungen wiederholt.

Verwandte Inhalte