Erstellen, Aktualisieren und Löschen von Elementen, die von Ihrer Anwendung über Microsoft Graph-Connectors hinzugefügt wurden

Artikel
11/15/2023

Microsoft Graph-Connectors bieten eine intuitive Möglichkeit, um externe Daten in Microsoft Graph zu verwenden. Elemente, die Ihre Anwendung dem Microsoft-Suchdienst hinzufügt, werden durch die externalItem-Ressource in Microsoft Graph dargestellt.

Nachdem Sie eine Verbindung herstellen, können Sie Ihre Inhalte hinzufügen. Jedes Element aus Ihrer Datenquelle muss als externalItem in Microsoft Graph mit einer eindeutigen Element-ID dargestellt werden. Diese ID wird verwendet, um das Element in Microsoft Graph zu erstellen, zu aktualisieren oder zu löschen. Sie können den Primärschlüssel aus Ihrer Datenquelle als Element-ID verwenden oder ihn aus einem oder mehreren Feldern ableiten.

Schlüsselkomponenten

Ein externalItem hat drei Schlüsselkomponenten: Zugriffsteuerungsliste, Eigenschaften und Inhalt.

Zugriffssteuerungsliste (ACL)

Die Zugriffssteuerungsliste (ACL) wird verwendet, um anzugeben, ob den gegebenen Rollen der Zugriff zum Anzeigen von Elementen in Microsoft-Erfahrungen gewährt oder verweigert wird. Die Zugriffssteuerungsliste ist ein Array von Zugriffssteuerungseinträgen, die eine Microsoft Entra Benutzer oder Gruppe darstellen. Ein dritter Zugriffssteuerungseintragstyp Everyone stellt alle Benutzer im Mandanten dar.

Beispiel für eine Zugriffssteuerungsliste.

Beispiel für eine Zugriffssteuerungsliste.

Der accessType-Wert deny hat Vorrang vor grant. So wird beispielsweise in dem zuvor gezeigten Element, während Everyone Zugriff gewährt wird und einem bestimmten Benutzer der Zugriff verweigert wird, die effektive Berechtigung für diesen Benutzer deny sein.

Wenn Ihre Datenquelle über Nicht-Azure AD-Gruppen verfügt (wie z. B. Teams innerhalb Ihres Helpdesksystems), die zum Festlegen von Berechtigungen für das Element verwendet werden, können Sie externe Gruppen in Microsoft Graph mithilfe der Gruppensynchronisierungs-APIs erstellen, um die Berechtigungenallow oder deny zu replizieren. Vermeiden Sie es, die Mitgliedschaft Ihrer externen Gruppen direkt in die ACLs der einzelnen Elemente zu erweitern, da jede Aktualisierung der Gruppenmitgliedschaft zu einer großen Zahl von Aktualisierungen der Elemente führen könnte.

Externe Gruppen umfassen eine andere Gruppe, Microsoft Entra Benutzer und Microsoft Entra Gruppen. Wenn Sie Nicht-Azure AD-Benutzer haben, müssen Sie diese in Microsoft Entra Benutzer in Ihrer ACL übersetzen.

Eigenschaften

Die Eigenschaftskomponente wird zum Hinzufügen von Metadaten für Elemente verwendet, die für Microsoft Graph-Erfahrungen nützlich sind. Sie müssen das Schema für die Verbindung registrieren, bevor Sie Elemente hinzufügen und Datentypen in unterstützte Datentypen konvertieren.

Beispiel für eine Eigenschaftskomponente.

Beispiel für eine Eigenschaftskomponente.

Inhalt

Die Inhaltskomponente fügt den Großteil des Elements hinzu, das volltextindiziert werden muss. Beispiele hierfür sind eine Ticket-Beschreibung, analysierter Text aus einem Dateitext oder ein Wiki-Seitentext.

Der Inhalt ist einer der Schlüsselbereiche, der die Relevanz aller Microsoft-Erfahrungen beeinflusst. Die Inhaltstypen text und html werden unterstützt. Wenn Ihre Datenquelle über andere Inhaltstypen verfügt, z. B. Binärdateien, Videos oder Bilder, können Sie diese nach Text analysieren, bevor sie Microsoft Graph hinzugefügt werden. Beispielsweise kann die optische Zeichenerkennung durchsuchbaren Text aus Bildern extrahieren.

Wichtig

Die Compliancelösung unterstützt text nur für den Inhaltstyp. Wenn Sie die Verbindung für Kompatibilität aktivieren, indem Sie die enabledContentExperience-Eigenschaft auf compliancefestlegen, sollten Sie Inhalt im Nur-Text-Format erfassen und den Inhaltstyp auf textfestlegen.

Abbildung einer Inhaltskomponente, deren Inhalt auf Text festgelegt ist.

Ein Beispiel für eine Inhaltskomponente.

Inhalte können nicht direkt zu einer Suchergebnisvorlage hinzugefügt werden, aber Sie können einen generierten Ergebnisausschnitt verwenden, bei dem es sich um eine dynamisch generierte Vorschau der relevanten Abschnitte innerhalb des Inhalts handelt.

Screenshot einer Suchergebnisvorlage.

Eine Suchergebnisvorlage.

Wenn sich der Inhalt in Ihrer Datenquelle ändert, müssen Sie ihn mit Ihren Verbindungselementen synchronisieren. Sie können entweder das gesamte Element oder eine oder mehrere Komponenten aktualisieren. Nachdem Sie Ihre Inhalte zu Microsoft Graph hinzugefügt haben, können Sie über die Microsoft Search-Benutzeroberfläche danach suchen, nachdem Sie Suchsparten und Ergebnistypen eingerichtet haben oder die Microsoft Graph-Search-API verwenden.

Aktivitäten

Die Aktivitätskomponente ist eine vorübergehende Eigenschaft, die Aktivitäten für das Element sendet. Sie können nur in diese Eigenschaft schreiben.

Eine Aktivität besteht aus einem Akteur (der die Aktivität ausgeführt hat), einem Zeitpunkt (zu dem die Aktivität ausgeführt wurde) und einem Aktivitätstyp (welcher Aktivitätstyp ausgeführt wurde). Die derzeit unterstützten Aktivitätstypen finden Sie im Abschnitt Beschreibung der type-Eigenschaft für eine externalActivity.

Das Senden von Aktivitäten für das Element unterstützt intelligente Empfehlungserfahrungen in Microsoft 365. Endbenutzer können basierend auf den gesendeten Aktivitäten auf sie zugeschnittene Inhalte erhalten.

Hinzufügen eines Elements

Um ein Element zum Index hinzufügen, müssen Sie ein „externalItem“ erstellen. Wenn Sie ein Element erstellen, weisen Sie in der URL einen eindeutigen Bezeichner zu.

Ihre Anwendung kann beispielsweise Helpdesk-Tickets anhand der Ticketnummer indizieren. Wenn ein Ticket die Ticketnummer SR00145 hat, sieht die Anforderung möglicherweise wie folgt aus:

PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

"properties": {
  "title": "WiFi outage in Conference Room A",
  "priority": 1,
  "assignee": "meganb@contoso.com"
}

Hinweis

Bevor indizierte Elemente in der Microsoft Search-Benutzeroberfläche gefunden werden können, muss ein Administrator für die entsprechende Verbindung die Suchergebnisseite anpassen.

Hinzufügen von Aktivitäten zu einem Element

Um einem Element Aktivitäten hinzuzufügen, rufen Sie den addActivities-Endpunkt mit demselben eindeutigen Bezeichner für dieses Element in der URL auf.

Wenn beispielsweise jemand mit Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52 am 11. April 2022 um 16:25 Uhr das Helpdeskticket mit der Ticketnummer SR00145 kommentiert hat, könnte die Anforderung zum Senden dieser Aktivität wie folgt aussehen.

POST /external/connections/contosohelpdesk/items/SR00145/addActivities
Content-Type: application/json

"activities": [
 {
   "type": "commented",
   "startDateTime": "2022-04-11T16:25:34.3202005Z",
   "performedBy": {
       "id": "18948b93-d3ed-4307-9981-10fc36a08a52",
       "type": "user"
    }
  }
]

Sie können auch eine Aktivität zu einem Element in derselben Anforderung hinzufügen, die das Element erstellt. Fügen Sie die Aktivität als eine andere Entität hinzu, z acl . B. und content. Wenn Sie eine Aktivität auf diese Weise hinzufügen, schließen Sie für die Aktivität ein @odata.type , oder die Anforderung schlägt fehl. Aktivitäten mit Zeitstempeln, die älter als sieben Tage sind, werden in der Microsoft 365-App nicht angezeigt. Endbenutzer können nur Aktivitäten in der Microsoft 365-App für Elemente anzeigen, auf die sie zugreifen können, und eine Aktivität haben (z. B. freigegeben, erstellt, bearbeitet usw.).

Aktualisieren eines Elements

Wenn ein Element im externen Dienst aktualisiert wird (das Helpdesk-Ticket wird neu zugewiesen, oder eine Produktbeschreibung wird aktualisiert), können Sie den Eintrag im Index aktualisieren, indem Sie das „externalItem“ aktualisieren und dazu den eindeutigen Bezeichner verwenden, der dem Element bei seiner Erstellung zugewiesen wurde.

PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json

{
  "assignee": "alexw@contoso.com"
}

Löschen eines Elements

Um Elemente aus dem Index zu entfernen, müssen Sie das „externalItem“ löschen und dazu den eindeutigen Bezeichner verwenden, der dem Element bei seiner Erstellung zugewiesen wurde.

DELETE /external/connections/contosohelpdesk/items/SR00145

Synchronisieren Ihrer Daten

Berücksichtigen Sie die folgenden Informationen, wenn Sie auswählen, wie Ihre Daten synchronisiert werden sollen:

Durchforstungsmechanismus:

Inkrementelle Durchforstung: Erkennt Und pusht Ergänzungen in Quelldaten; Weniger leistungsintensiv als eine vollständige Durchforstung.
Vollständige Durchforstung: Updates des gesamten Elements aus den Quelldaten (erneute Durchforstung), wobei alle Ergänzungen und Löschungen erfasst werden; stellt eine bessere Genauigkeit sicher, ist aber zeitaufwendiger und leistungsintensiver als eine inkrementelle Durchforstung.

Synchronisierungsintervall:

Ereignisbasiert: Pusht Elementupdates auf Ereignisbasis. Es wird empfohlen, dieses Synchronisierungsintervall für dynamische oder vertrauliche Daten wie element status zu verwenden.
Geplant: Pusht Elementupdates in regelmäßigen Abständen (alle N Minuten). Es wird empfohlen, dieses Synchronisierungsintervall für inhaltsreiche oder nicht vertrauliche Daten zu verwenden, die weniger häufig aktualisiert werden, z. B. Wikis oder Webseiten.

Letztendlich hängt die Wahl der Datenaktualisierungsstrategie von Ihrem Datentyp und ihren Computefunktionen ab.