SharePoint Graph API

Mit dieser Schnittstelle kann die offizielle SharePoint Graph API von Microsoft integriert werden, um mit einem SharePoint Verzeichnis zu kommunizieren.
Dafür
Dafür ist eine registrierte Microsoft Azure Applikation notwendig.

Integrierte Services der Graph API

• Dokumente in ein zuvor definiertes SharePoint Verzeichnis hochladen

Zugangsberechtigungen in Microsoft Azure

BenötigteBenötigte Applikationen

Es werden zwei Applikationen benötigt,benötigt, in Microsoft Azure.

Eine dient zu administrativen zwecken, die andereAndere fürfür den Nutzer selbst. Zum bewilligen der folgenden Rechte wird ein User mit Administrationsrechten benötigt.
benötigt.
Die Rechte könnenkönnen im MenüMenü "API Permissions" hinzugefügthinzugefügt werden:

• Die Admin-Applikation benötigtbenötigt die Rechte Sites.FullControl.All
• Die Nutzer-Applikation benötigtbenötigt die Rechte Sites.Selected

In der Admin-Applikation muss ein User im MenüMenü Certificates & secrets erstellt werden. Dieser User ist nötig,nötig, um die Nutzer-Applikation mit den nötigennötigen Rechten auszustatten.

Rechte fürfür die Nutzer-Applikation

FürFür diesen Abschnitt benötigenbenötigen Sie die Daten der Admin-Applikation.  

Einloggen

Zu erst benötigenbenötigen Sie einen Bearer Token, um sich an der API zu authentifizieren. Dies erfolgt durch folgenden Request:

• URL: https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
• HTTP Methode: POST
• Request Body Typ: form-data
• Request Body:
  • client_id:<CLIENT_ID>
  • client_secret:<CLIENT_SECRET>
  • grant_type:client_credentials
  • scope:https://graph.microsoft.com/.default

Statt "<TENANT_ID>", "<CLIENT_ID>" und "<CLIENT_SECRET>" müssenmüssen Sie ihreIhre jeweiligen Daten verwenden. Wo Sie diese Daten finden steht in den Abschnitten "Feld Tenant Id", "Feld Client Id" und "Feld Client Secret" dieses Artikels.

Anbei der cURL Befehl:

curl --location 'https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token' \--form 'client_id="<CLIENT_ID>"' \--form 'client_secret="<CLIENT_SECRET>"' \--form 'grant_type="client_credentials"' \--form 'scope="https://graph.microsoft.com/.default"'

Site Id erhalten

• URL: https://graph.microsoft.com/v1.0/sites/<TENANT>.sharepoint.com/sites/<NAME>
• HTTP Methode: GET
• Header: "Authorization: Bearer <BEARER_TOKEN>"

Anbei der cURL Befehl:

curl --location 'https://graph.microsoft.com/v1.0/sites/<TENANT>.sharepoint.com:/sites/<NAME>' \--header 'Authorization: Bearer <BEARER_TOKEN>'

Die Response dieses Requests ist etwas umständlicherumständlicher zu lesen, ein Beispiel:

{

  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites/$entity",

  "createdDateTime": "2025-03-13T00:11:15.033Z",

  "description": "TestDescription",

  "id": "<TENANT>.sharepoint.com,808dec17-aa6d-4158-a9fe-8caa8d909dff,81f7ad14-65ae-46c2-b0fc-10602e9401cc",

  "lastModifiedDateTime": "2025-03-13T07:07:19Z",

  "name": "TestName",

  "webUrl": "https://<TENANT>.sharepoint.com/sites/<SITE_NAME>",

  "displayName": "TestName",

  "root": {},

  "siteCollection": {

    "hostname": "<TENANT>.sharepoint.com"

  }

}

Die Site Id in diesem Fall ist der Wert 808dec17-aa6d-4158-a9fe-8caa8d909dff. Er befindet sich im Index "id" und ist der mittlere der Werte (wenn den Wert an seinen Kommata aufteilt).

Zugriffsrechte erteilen

FürFür die Zugriffsrechte benötigenbenötigen sie die Client ID der Nutzer Applikation und den Namen. Diese setzen Sie an der Stelle von "<NUTZER_APPLIKATION_CLIENT_ID>" bzw. "<NUTZER_APPLIKATION_NAME>" ein.

Die Rechte zum Schreiben beinhalten auch die Leserechte.

• URL: https://graph.microsoft.com/v1.0/sites/<SITE_ID>/permissions
• HTTP Methode: POST
• Request Body Type: JSON
• Request Body:
  
  

  • {
    
      "roles": [
    
        "write"
    
      ],
    
      "grantedToIdentities": [
    
        {
    
          "application": {
    
            "id": "<NUTZER_APPLIKATION_CLIENT_ID>",
    
            "displayName": "<NUTZER_APPLIKATION_NAME>"
    
          }
    
        }
    
      ]
    
    }

Anbei der cURL Befehl:

curl --location 'https://graph.microsoft.com/v1.0/sites/<SITE_ID>/permissions' \
--header 'Authorization: Bearer <BEARER_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "roles": ["write"],
  "grantedToIdentities": [{
    "application": {
      "id": "<NUTZER_APPLIKATION_CLIENT_ID>",
      "displayName": "<NUTZER_APPLIKATION_NAME>"
    }
  }]
}'

Der Server gibt im Erfolgsfall eine Response mit dem Statuscode 201 zurück, im Erfolgsfall.zurück. Der Inhalt der Response ist fürfür die folgenden Zwecke unnötig,unnötig, weshalb an dieser Stelle nicht weiter darauf eingegangen wird.

Konfiguration

Um diese Schnittstelle zu verwenden und Aktionen auszuführen,auszuführen, muss an der Squeeze Dokumentenklasse eine Export-Schnittstelle definiert werden.

Die benötigtenbenötigten Zugangsdaten entnehmen Sie aus der Nutzer-Applikation.

Authentifizierung

_{Abbildung - Export Interface SharePoint GraphAPI (WIP)}

Feld Beschreibung

FürFür das Export Interface kann ein Name angegeben werden, im Feld Beschreibung.

Feld Host

In diesem Feld wird die Adresse zur SharePoint Seite hinterlegt. Diese hat folgendes Muster: <TENANT>.sharepoint.com/sites/<NAME>.

Feld Tenant Id

Die Tenant Id befindet sich in der ÜbersichtÜbersicht einer registrierten App. Eine Auflistung dieser Apps finden sie hier.

Um die Liste zu sehen müssenmüssen Sie eingeloggt sein.

Die Tenant Id wird auf der Seite auch "Directory (tenant) ID".

Feld Client Id

Die Tenant Id befindet sich in der ÜbersichtÜbersicht einer registrierten App. Eine Auflistung dieser Apps finden sie hier.

Um die Liste zu sehen müssenmüssen Sie eingeloggt sein.

Hier wird sie auch unter dem Begriff "Application (client) ID" geführt.geführt.

Feld Client Secret

Die Tenant Id befindet sich in der ÜbersichtÜbersicht einer registrierten App. Eine Auflistung dieser Apps finden sie hier.

Um die Liste zu sehen müssenmüssen Sie eingeloggt sein.

Das Client Secret wird innerhalb der registrierten App hinterlegt. Das dafürdafür nötigenötige MenüMenü finden Sie in, in der ausgewähltenausgewählten App, unter dem MenüMenü "Certificates & secrets".

FürFür das Erstellen eines Secrets müssenmüssen sie lediglich eine aussagekräftigeaussagekräftige Beschreibung angeben, und den Zeitraum, in welchem das Secret valide ist.

Das Client Secret wird bei Microsoft unter "Secret Value" geführt.geführt. Diese Information Information wird nur einmalig angezeigt, aus diesem Grund sollte es in einer sicheren Umgebung gespeichert werden.

Verwechseln Sie das Client Secret nicht mit "Secret Value".

Feld Entity

ÜberÜber die Entity wird der Service ausgewählt,ausgewählt, welchen Sie verwenden möchten:möchten:

• SharePoint Document Export
  • Service um ein Dokument hochzuladen

Feld Export Folder Structure

Dateien werden alle in das Home Verzeichnis des SharePoint Verzeichnisses hochgeladen.

Um zu spezifizieren, in welche Verzeichnis Struktur ein Dokument abgelegt werden soll, könnenkönnen in dieser Auswahlliste mehrere Felder ausgewähltausgewählt werden.

Die Felder werden durch ihre in SQUEEZE erkannten Daten ersetzt. So könntekönnte beispielsweise die Auswahl des Feldes "IBAN" dazu führen,führen, dass ein Dokument in das Verzeichnis der erkannten IBAN abgelegt wird (nicht in einem Verzeichnis mit dem Namen "IBAN").

Feld Drive

Wenn der Host, die Tenant ID, die Client ID und das Client Secret angegeben sind, wird überprüftüberprüft ob die Daten korrekt sind und eine Verbindung mit der Graph API erfolgreich zustande kommt.

In diesem Fall wird im Feld Drive  eine Liste von möglichenmöglichen Verzeichnissen aufgeführt,aufgeführt, welches als Home Verzeichnis des SharePoints dienen soll, das Sie auswählenauswählen müssen. müssen. 

Feld Create Folder Structure

Um die Funktion zu verwenden, dass ein Pfad Verzeichnis erstellt werden soll, auch wenn es nicht existiert, muss der Feldwert "Ja" sein. Sollte das Verzeichnis bereits existieren wird kein neues Verzeichnis erstellt.

Der Pfad fürfür das Verzeichnis wird durch das Feld Export Folder Structure bestimmt.

Sollte der Feldwert "Nein" lauten, dann wird geprüftgeprüft ob der Verzeichnis Pfad existiert. Wenn dies der Fall ist, dann werden die verarbeiteten Dokumente hochgeladen.

Existiert das Verzeichnis jedoch nicht, dann wird das Dokument nicht hochgeladen und ein Fehler wird ausgegeben, bei der Validierung.

Dadurch soll vermieden werden, das unerwartete Verzeichnisse erstellt und Dokumente ggf. verschwinden.

Beispiel

_{Abbildung - Beispiel ausgefülltesausgefülltes Formular fürfür Export Interface (WIP)}

Wenn wir eine neue Applikation in Microsoft Azure erstellt haben, rufen wir diese auf und erhalten folgende Ansicht.

_{Abbildung - Registrierte Microsoft Applikation "Neue SharePoint Applikation"}

Auf dieser Abbildung ist zu sehen was die Client ID ist, sowie wo die Tenant ID zu finden ist.

Bei Auswahl des MenüsMenüs "Certificates & secrets" existiert ein kleiner Button mit dem Namen "New client secrets". Nachdem die nötigennötigen Daten angegeben wurden erhalten wir einen neuen Eintrag:

Feldwerte / Metadaten exportieren

Um Feldwerte als Metadaten zu exportieren, beim Upload, müssenmüssen diese in der Dokumentenklasse angegeben werden.
Dafür
Dafür muss das nötigenötige Feld ausgewähltausgewählt werden, und der entsprechende Wert muss im Feld "Name (Zielsystem)" eingetragen werden.

_{Abbildung - Kopfdaten-Felder der Dokumentenklasse}