Skip to main content
Skip table of contents

Übersicht über die Eigenheiten des SharePoint Graph-API-Moduls

In diesem Artikel lernen Sie die Besonderheiten und Eigenheiten des Moduls SharePoint Graph-API (ID=spog) in edoc content services kennen. Dieses Modul ist für die Kommunikation mit SharePoint-Instanzen konzipiert, die in Microsoft Azure gehostetet werden.

Verwendete Authentifizierungsmethode im SharePoint Graph-API-Modul

Der SharePoint Graph-API unterstützt als Authentifizierung das Open Authorization 2-Protokoll (OAuth2).

Damit edoc content services auf die Microsoft Graph-API zugreifen kann, müssen Sie im Azure Active Directory im Azure Portal eine App registrieren. Sie erhalten nach der Registrierung die für Verbindungszeichenfolge (ConnectionString) notwendigen Parameter TenantId und ClientId.

Zusätzlich müssen Sie im Azure Portal unter Zertifikate & Geheimnisse einen geheimen Clientschlüssel (client secret) erstellen. Geben Sie dann in der Verbindungszeichenfolge den Wert für den geheimen Clientschlüssel als Wert für den Parameter ClientSecret ein.

Notwendige Berechtigungen im Azure Portal für das SharePoint Graph-API-Modul

Damit edoc content services auf die SharePoint-Dokumente über die Microsoft Graph-API zugreifen kann, müssen Sie im Azure Portal die entsprechenden API-Berechtigungen erteilen.

Sie haben die Möglichkeit, edoc content services den Zugriff auf alle SharePoint-Seiten oder nur auf bestimmte SharePoint-Seiten zu erteilen

Sie müssen folgende Anwendungsberechtigungen erteilen, wenn der Zugriff auf alle SharePoint-Seiten erfolgen soll:

  • API-Name: SharePoint

    • Berechtigungsname: Sites.ReadWrite.All

Erteilen Sie für die Anwendungsberechtigungen unbedingt die Administratorzustimmung. Auf diese Weise erhält edoc content services auf alle SharePoint-Seiten des Mandanten (Tenant) Zugriff.

Sie können den Zugriff auch nur auf bestimmte SharePoint-Seiten erteilen.

Sie müssen folgende Anwendungsberechtigungen erteilen, wenn der Zugriff nur auf bestimmte SharePoint-Seiten erfolgen soll:

  • API-Name: Microsoft Graph

    • Berechtigungsname: Sites.Selected

Sie müssen anschließend auf der jeweiligen SharePoint-Seite die Berechtigung erteilen.

So geht’s

  1. Rufen Sie die entsprechende Seite im Browser auf und fügen Sie an die URL der Seite Folgendes an: /_layouts/15/AppInv.aspx.

  2. Tragen Sie auf der Seite die App-ID der erstellten Azure AD-App (Client-ID) ein.

  3. Klicken Sie auf Nachschlagen, damit der Titel automatisch gefüllt wird.

  4. Tragen Sie die App-Domäne und die Umleitungs-URL (Redirect) in die entsprechenden Felder ein.

  5. Geben Sie im Feld Berechtigungsanforderungs-XML den folgenden Code ein:

XML 
<AppPermissionRequests AllowAppOnlyPolicy="true">
    <AppPermissionRequest Scope=http://sharepoint/content/sitecollection Right="FullControl" />
</AppPermissionRequests>

6. Klicken Sie auf Erstellen.

Funktion des ConnectionString-Parameters “ListId“

Sie können in Microsoft SharePoint Listen und Dokumentbibliotheken erstellen.

Mit dem ConnectionString-Parameter ListId teilen Sie edoc content services mit, zu welche dieser Listen oder Dokumentbibliotheken Sie eine Verbindung herstellen möchten. In Microsoft SharePoint werden Listen und Dokumentbibliotheken technisch gleich, sodass der Parameter ListId für beides verwendet wird.

So finden Sie die ID einer Liste oder Dokumentbibliothek in SharePoint:

  1. Rufen Sie Liste oder Dokumentbibliothek im Browser auf.

  2. Klicken Sie auf Einstellungen (das Zahnrad-Symbol).

  3. Klicken Sie auf die Option Listeneinstellungen bzw. Bibliothekseinstellungen. Wenn Sie auf Bibliothekseinstellungen klicken, müssen Sie noch zusätzlich auf Weitere Bibliothekseinstellungen klicken.

  4. Kopieren Sie aus dem Adressfeld des Browsers die ID aus der URL der Einstellungsseite.

In der Internetadresse dieser Einstellungsseite befindet sich die gesuchte ID zwischen den geschweiften Klammern am Ende der URL.

https://myTenant.sharepoint.com/_layouts/15/listedit.aspx?List={e6748c56-669e-4b21-b4f6-a31b2f54c936}

Der Wert für ListId lautet im Beispiel e6748c56-669e-4b21-b4f6-a31b2f54c936.

Gut zu wissen

Wenn Sie die gesamte URL aus der Adressleiste des Browsers kopieren und woanders einfügen, werden Sie keine geschweiften Klammern finden. Bestimmte Zeichen (z.B. Leerzeichen, runde Klammern, geschweifte Klammern) werden in der URL maskiert. Geschweifte Klammern werden mit der Zeichenfolge %7D maskiert, sodass die URL im Beispiel so aussieht:

https://myTenant.sharepoint.com/_layouts/15/listedit.aspx?List=%7De6748c56-669e-4b21-b4f6-a31b2f54c936%7D

Der Wert für ListId befindet sich zwischen den beiden Zeichenfolgen %7D.

Was passiert bei der Aktion “ConnectionTest”?

Wenn Sie den Endpunkt GET /ConnectionTest aufrufen, wird Folgendes durchgeführt:

  • Die Anmeldung in SharePoint wird durchgeführt.

  • Die technischen Eigenschaften der angegebenen Liste oder Dokumentbibliothek werden an edoc content services zurückgegeben.

Auf diese Weise wird sichergestellt, dass sowohl die Parameter user und password als auch der Parameter ListId korrekt sind.

Was sind Kategorien im Modul?

Mit dem Endpunkt GET /Categories rufen Sie die Struktur einer Liste oder einer Dokumentbibliothek ab. Eine Kategorie im Kontext des Moduls in edoc content services repräsentiert eine Liste oder Dokumentbibliothek und die jeweiligen Spalten in Microsoft SharePoint.

Wie werden Inhaltstypen (Content types) berücksichtigt?

Wenn Sie den Endpunkt GET /Categories abrufen, werden zusätzlich zur Struktur der Liste oder Dokumentbibliothek auch die Inhaltstypen zurückgeliefert. Sie erkennen die Inhaltstypen an der ID und dem Namen. In der ID und im Namen der Liste oder der Dokumentbibliothek befinden sich die ID und der Name des Inhaltstyps getrennt durch ein Pipe-Zeichen (|).

JSON 
[
  {
    "properties": [
      {
        "id": "Title",
        "name": "Title",
        "type": "Text",
        "isRequired": false,
        "alias": "Title"
      },
      {
        "id": "invoice_x0020_number",
        "name": "invoice number",
        "type": "Text",
        "isRequired": false,
        "alias": "invoice number"
      },
    ],
    "id": "e6748c56-669e-4b21-b4f6-a31b2f54c936",
    "name": "invoice library"
  },
  {
    "properties": [
      {
        "id": "Title",
        "name": "Title",
        "type": "Text",
        "isRequired": false,
        "alias": "Title"
      },
      {
        "id": "invoice_x0020_date",
        "name": "invoice date",
        "type": "DateTime",
        "isRequired": false,
        "alias": "invoice date"
      }
    ],
    "id": "e6748c56-669e-4b21-b4f6-a31b2f54c936|0x01010082946529B238E9498A2926B1E7699B6F",
    "name": "invoice library|document"
  }
]

Besonderheiten bei der Behandlung von Dateinamen

Der Dateiname einer Datei, die mit edoc content services in SharePoint hochgeladen wird, ändert sich aus zwei Gründen:

  • Innerhalb einer Dokumentbibliothek muss der Dateiname eindeutig sein. In der Praxis kommt es aber oft vor, dass es gleichlautende Dateinamen gibt. Wenn Sie z.B. Dateianhänge von E-Mails archivieren, können viele Anhänge einfach nur Rechnung.pdf heißen. Damit die Anhänge eindeutig identifiziert werden können, wird ein Zeitstempel (Zeitpunkt des Uploads der Datei) als Präfix in den Dateinamen eingefügt. Aus dem Dateinamen Rechnung.pdf wird 2022-10-07-12-40-05-877517_Rechnung.pdf.

  • In SharePoint sind eine Reihe von Zeichen in Dateinamen unzulässig. Einige der unzulässigen Zeichen in SharePoint sind in den meisten Betriebssystemen gültige Zeichen für einen Dateinamen. Wenn diese in SharePoint ungültigen Zeichen im Dateinamen enthalten sind, werden sie durch einen Unterstrich (_) ersetzt. Aus invoice-smith&sons.pdf wird invice-smith_sons.pdf. Folgende Zeichen werden standardmäßig ersetzt: ', #, ~, \, %, &, *, :, <, >, ?, /, {, }, |, “. Ein Punkt (.) im Dateinamen wird ebenfalls ersetzt, außer es handelt sich um das Trennzeichen zwischen Dateiname und Dateierweiterung.

Hochladen einer neuen Dateiversion inklusive Ändern der Dokumenteneigenschaften

Sie können im Modul mit dem Endpunkt POST /Documents/{documentId} eine neue Version der Datei in ein vorhandenes Dokument hochladen und gleichzeitig die Eigenschaften dieses Dokuments ändern.

Suchen nach Dokumenten

Sie können mit dem Endpunkt POST /Documents/search nach Dokumenten suchen, indem Sie mehrere Eigenschaften und Werte als Suchkriterium angeben. Die gesuchten Dokumente müssen den angegebenen Wert in der angegebenen Eigenschaft enthalten.

Wenn Sie z.B. mehrere Suchkriterien werden bei der Suche mit UND verknüpft. Im folgenden Beispiel werden alle Dokumente zurückgeliefert, die die Lieferantennummer 1234 haben und als Typ Rechnung eingetragen haben und die bezahlt sind.

JSON 
{
  "vendor number": "1234",
  "type": "invoice",
  "paid": "false"
}

Eindeutiges Dokument über die Grenzen einer Dokumentbibliothek hinweg (ecmDocumentGuid)

Immer wenn Sie ein neues Dokument in einer Dokumentbibliothek in SharePoint erstellen, erhält das Dokument automatisch eine ID. Diese IDs beginnen mit 1 und werden fortlaufend hochgezählt. In der Praxis kommt es vor, dass Sie Dokumente von einer Dokumentbibliothek in eine andere Dokumentbibliothek verschieben möchten. Das Verschieben eines Dokuments ist prinzipiell technisch möglich, aber verschobene Dokument erhält von SharePoint eine neue ID, da die IDs in einer Dokumentbibliothek immer eindeutig sein müssen. Mit einer neuen ID verlieren Sie jedoch die Referenz in externen Systemen.

edoc content services bietet einen Mechanismus, um dieses Problem zu umgehen:

Fügen Sie in SharePoint in den Dokumentbibliotheken die Spalte ecmDocumentGuid (muss exakt so heißen) ein. Diese Spalte wird von edoc content services erkannt.

Sobald Sie ein neues Dokument erstellen, wird diese Spalte automatisch mit einer neu generierten GUID (Globally Unique Identifier) gefüllt. Die neue GUID ist immer eindeutig, ganz gleich in welche Dokumentbibliothek Sie das Dokument verschieben.

Die ID eines Dokuments in der Spalte ecmDocumentGuid sieht dann so aus: 53D67D38-F9AE-42A9-8360-24AE59DA55F0.

Besonderheiten von “NewDocuments” zum Auslesen neuer Dokumente

Sie haben zwei unterschiedliche Optionen, neue Dokumente in einem ECM-System abzurufen:

  • Mit dem Endpunkt POST /Documents/newDocuments können Sie im ECM-System neue Dokumente auslesen. Sie müssen im Endpunkt in der Eigenschaft lastDocumentIndex die ID des letzten Dokuments angeben. edoc content services sucht dann nach allen Dokumenten deren ID größer als lastDocumentIndex ist.

  • Wenn die Dokumentbibliothek die Spalte ecmDocumentGuid hat, muss lastDocumentIndex mit dem Wert aus ecmDocumentGuid gefüllt werden. Wenn Dokumente ohne Wert in der Spalte ecmDocumentGuid gefunden werden, wird automatisch ein Prozess von edoc content services ausgeführt, bei dem diese Spalte gefüllt wird. Nach Abschluss des Prozesses haben alle Dokumente in der Spalte ecmDocumentGuid einen entsprechenden Wert.

Weitere Informationen zum Prüfen von neuen Dokumenten finden Sie unter: Prüfen, ob neue Dokumente im Zielsystem vorhanden sind

Was bedeutet “Akte” (Folder) im Modul?

Im Kontext von Microsoft SharePoint sind ECM-Akten immer Einträge in einer separaten Liste. ECM-Akten (Folder) können in SharePoint niemals Einträge in einer Dokumentbibliothek sein.

Die Einträge in der SharePoint-Liste können Daten einer ECM-Akte enthalten, wie z.B. die Lieferantennummer. Sie implementieren die Logik, welche Daten in welcher Relation gespeichert werden, in der Anwendung, mit der edoc content services aufgerufen wird.

Weitere Informationen zu ECM-Akten finden Sie unter: Funktionen zum Verwalten von Akten (Folders)

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close