Query-Parameter

Query-Parameter werden einer API-Anfrage hinzugefügt. Dabei kann es sich um optionale Filter handeln oder um verpflichtende Werte, ohne die eine Anfrage nicht möglich ist. Standardmäßig wird pro Parameter genau eine Anfrage gestellt. D.h. für 10 statische Parameter, die nicht als Default markiert sind, werden 10 API-Anfragen durchgeführt und der jeweilige Parameter übergeben. Jedes Abfrage-Ergebnis wird daraufhin in die Datenbank geschrieben.

• Default Parameter = true: Parameter wird jeder API-Anfrage hinzugefügt, (i. d. R. für Pflichtparameter benötigt).
• URL Parameter = true: Parameter wird im URI-Pattern ersetzt (vorausgesetzt es gibt eine Entsprechung zum Parameter-Key) und nicht als Query-Parameter hinzugefügt.
• URL Parameter = false: Parameter wird an die Abfrage-URL angehangen.
• Body Parameter = true: Dieser Parameter kann im Request-Body genutzt werden.
• Add Mapping:
  Die Parameterwerte werden einer Mappingtabelle hinzugefügt. Dadurch können Relationen zwischen voneinander abhängigen Ressourcen hergestellt werden. Für jeden Parameterwert entsteht dabei ein zusätzlicher Eintrag mit den passenden IDs (Spalte __id).

  Die Mapping-Tabelle wird nach folgendem Muster erstellt:
  {Schema}.{Quell-Tabelle des Parameters}{Zieltabelle der Ressource}
  Beispiel: GraphApi.UserUserDetails)

Beispiele:

• Uri Pattern = {Resource}/{id} | URL-Parameter = true 
  https://graph.microsoft.com/v1.0/users/ID_WERT
• Uri Pattern = {Resource}/suburl | URL-Parameter = false:
  https://graph.microsoft.com/v1.0/users/suburl?id=ID_WERT
• Uri Pattern = {Resource}/{parameter1}/{parameter2} | Mehrere Default Parameter = true und URL-Parameter = true:
  • https://graph.microsoft.com/v1.0/users/WERT1/WERT2
• Uri Pattern = {Resource} | Mehrere Default Parameter = true und URL-Parameter = false: (also Query-Parameter)
  • https://graph.microsoft.com/v1.0/users?parameter1=WERT1&parameter2=WERT2

Statische Parameter

Statische Parameter sind vom Typ Value. Um die Tabellenstruktur konfigurieren und erstellen zu können, kann es erforderlich sein, dass ein statischer "Beispiel"-Parameter erstellt werden muss, der zur manuellen API-Frage dient und ein repräsentatives Ergebnis zurückliefert.

Im folgenden Beispiel wird die API-Ressource users mit dem URL-Parameter id abgefragt, welche zusätzliche Details zu einem einzelnen users-Objekt zurückgibt. Dafür wird eine ID aus dem vorherigen, allgemeinen Abfrageergebnis der users-Ressource benötigt. Solche Zusammenhänge sind in der Regel der jeweiligen API-Dokumentation zu entnehmen oder können durch Analyse der Abfrageergebnisse ermittelt werden.

Im oberen Bereich der Parameterkonfiguration wird eine Vorschau der auszuführenden Abfrage-URL angezeigt. Der Parameter id wurde im URI-Pattern ersetzt, da die Option „URL Parameter“ aktiviert ist. Ist diese Option nicht aktiviert, wird stattdessen ein Query-Parameter an die Abfrage-URL angehängt.

Aufbau der Abfrage-URL:
{BaseUri}/{Version}/{Uri Pattern} -> {BaseUri}/{Version}/{Resource}/{id} 
-> https://graph.microsoft.com/v1.0/users/ID_WERT

Nachfolgend kann der Parameter auf der Seite Table Configuration ausgewählt und eine Abfrage damit gestartet werden.

In diesem Beispiel werden einige Werte zurückgegeben, die in der allgemeinen Anfrage nicht vorhanden waren. Werte, die bereits in der ersten Ressource erfasst wurden, können hier deaktiviert bleiben.