Metadata Query-API

Das Metadata Query-API ist eine Schnittstelle, um kundenspezifische, ausschließlich lesende SQL-Abfragen auf die Metadata SQL Views abzusetzen und die Ergebnisse in unterschiedlichen, gängigen Formaten herunterzuladen.

Hinweis

In den nachfolgenden Beispielen werden zur Veranschaulichung der Server https://www.myserver.com und die Datenbank test verwendet (z.B. im Pfad https://www.myserver.com/api/test/queries/download). Der Server und die Datenbank sind in allen echten Aufrufen entsprechend zu ersetzen. Je nach Konfiguration muss die URL gegebenenfalls auch noch um den Context-Path erweitert werden (z.B. https://www.myserver.com/dataspot/api/test/queries/download).

Wichtig

Für den Betrieb des Metadata Query-API muss ein entsprechender Benutzer konfiguriert sein (siehe Server-Parameter DATASPOT_POSTGRES_READONLY_USER), welcher lesende Berechtigungen für alle Metadata SQL Views hat. Alle SQL-Anweisungen des Metadata Query-API werden ausschließlich mit diesem Benutzer durchgeführt.

Metamodell

Die SQL-Abfragen richten sich nach dem Metamodell. Das Metamodell dokumentiert alle Eigenschaften und Beziehungen der Metadatenobjekte und bildet die Grundlage für das Metadata Query-API. Das Metamodell ist in der Datenbank meta unter folgender URL erreichbar:

https://www.myserver.com/web/meta

Hinweis

Die Datenbank meta kann in der Admin-Konsole (https://www.myserver.com/web/admin) erzeugt werden.

Query-API

Das Metadata Query-API ist eine Programmierschnittstelle, mit welcher (analog zur Metadaten-Abfrage in der Benutzeroberfläche) kundenspezifische, ausschließlich lesende SQL-Abfragen auf die Metadata SQL Views abgesetzt werden können:

Die Properties richten sich nach der jeweiligen, kundenspezifischen SQL-Anweisung.
Die abgefragten Metadaten können in verschiedenen Formaten bereitgestellt werden.

Funktionsweise

Das Metadata Query-API führt eine kundenspezifische SQL-Anweisung auf die Metadata SQL Views durch und liefert das Ergebnis im gewählten Format.

Achtung

Es ist nicht möglich, schreibende SQL-Anweisungen auszuführen. Die Transaktion in PostgreSQL wird als ausschließlich lesende Transaktion gestartet und zusätzlich mehrfach gegen schreibende SQL-Anweisungen abgesichert.

Optionen

Das Metadata Query-API wird mit folgender URL aufgerufen:

https://www.myserver.com/api/test/queries/download

Die SQL-Anweisung wird in JSON eingebettet und in der HTTP-Nachricht (Request-Payload) übertragen.

{
  "sql": "select * from classifier_view"
}

Die Optionen werden als Query-Parameter in der URL übergeben.

Option `format`

Die Option format definiert das Format der abgefragten Metadaten.

`format`	Format	Internet Media Type
`CSV`	CSV	`text/csv`
`JSON`	JSON	`application/json`
`XML`	XML	`application/xml`

/download?format=CSV
/download?format=JSON
/download?format=XML

Option `language`

Die Option language definiert die Sprache.

`language`	Sprache
	Standardsprache des Servers
`de`	Deutsch
`en`	Englisch

/download?language=de
/download?language=en

Hinweis

Alternativ kann die Sprache im HTTP-Header Attribut Accept-Language definiert werden, wird jedoch von der gegebenenfalls vorhandenen Option language überschrieben.

Accept-Language: de
Accept-Language: en

Option `version`

Die Option version definiert einen Zeitpunkt in der Historie, um die Metadaten im Zustand zum gewählten Zeitpunkt aus den versionierten Metadata SQL Views (z.B. collection_version_view) abzufragen.

`version`	Beschreibung
	Die Metadaten werden im aktuellsten Zustand abgefragt.
Zeitstempel (Epoche) in Millisekunden	Die Metadaten werden im Zustand zum gewählten Zeitpunkt abgefragt.

/download?version=1698676897000

Die Option version wird bei Abfragen auf die versionierten Metadata SQL Views (z.B. collection_version_view) automatisch angewendet, d.h. der Zeitstempel muss nicht explizit in der SQL-Anweisung angegeben werden.

select * from collection_version_view -- alle Sammlungen zum definierten Zeitpunkt abfragen

Hinweis

Alternativ kann der Zeitstempel im HTTP-Header Attribut Accept-Version definiert werden, wird jedoch von der gegebenenfalls vorhandenen Option version überschrieben.

Accept-Version: 1698676897000

HTTP-Methoden

Die HTTP-Methode PUT bzw. POST definiert, dass das Metadata Query-API synchron bzw. asynchron aufgerufen wird.

HTTP‑Methode	Beschreibung
`PUT`	Das Metadata Query-API wird synchron aufgerufen. Der Aufruf wartet, bis die Abfrage vollständig durchgeführt ist, und gibt danach die abgefragten Metadaten oder eine Fehlermeldung zurück.
`POST`	Das Metadata Query-API wird asynchron aufgerufen. Der Aufruf startet einen Job, der im Hintergrund läuft und die abgefragten Metadaten im gewählten Format bereitstellt. Wenn der Job fertig ist können die abgefragten Metadaten heruntergeladen sowie die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Aufruf

Für die nachfolgenden Beispiele wird das Open-Source Tool curl verwendet. Alternativ ist jede beliebige Bibliothek geeignet, die über HTTP kommunizieren kann.

Hinweis

Aus Gründen der Übersichtlichkeit sind die HTTP-Nachrichten in den Beispielen vereinfacht oder verkürzt dargestellt.

Hinweis

Für die Aufrufe sind Zugangsdaten (z.B. <user> und <password>) erforderlich. Je nach Authentifizierungsmethode (Benutzerkennung und Passwort, Single Sign-On, Same Sign-In, OpenID Connect) und eingesetzten Tools (z.B. curl) können unterschiedliche Mechanismen (z.B. Basic Authentication, Bearer Token) notwendig sein, um die Zugangsdaten bereitzustellen.

Der entsprechende Benutzer muss erfasst und als Administrator berechtigt sein.

Metadata Query-API (synchron)

Das Metadata Query-API kann mit der HTTP-Methode PUT und der Option format aufgerufen werden, um Metadaten synchron abzufragen. Mit den Optionen -H "Content-Type: application/json" und -d kann eine SQL-Anweisung <statement> in JSON eingebettet und in der HTTP-Nachricht (Request-Payload) übertragen werden.

curl -X PUT -u <user>:<password> -H "Content-Type: application/json" -d "{\"sql\":\"<statement>\"}" "https://www.myserver.com/api/test/queries/download?format=<format>"

Der Aufruf wartet, bis die Abfrage vollständig durchgeführt ist, und gibt danach die abgefragten Metadaten oder eine Fehlermeldung zurück.

Beispiel: Metadaten abfragen (synchron)

curl -X PUT -u jdoe:s3cr3t -H "Content-Type: application/json" -d "{\"sql\":\"select * from classifier_view\"}" "https://www.myserver.com/api/test/queries/download?format=CSV"
curl -X PUT -u jdoe:s3cr3t -H "Accept-Language: de" -H "Content-Type: application/json" -d "{\"sql\":\"select * from attribute_view\"}" "https://www.myserver.com/api/test/queries/download?format=JSON"

Beispiel: Ablauf und Fehlerbehandlung (synchron)

Das Metadata Query-API wird mit der HTTP-Methode PUT und der Option format=CSV aufgerufen, um Metadaten synchron abzufragen. Mit den Optionen -H "Content-Type: application/json" und -d wird die SQL-Anweisung select id, label, date_created from classifier_view in JSON eingebettet und in der HTTP-Nachricht (Request-Payload) übertragen.

curl -X PUT -u jdoe:s3cr3t -H "Content-Type: application/json" -d "{\"sql\":\"select id, label, date_created from classifier_view\"}" "https://www.myserver.com/api/test/queries/download?format=CSV"

PUT /api/test/queries/download?format=CSV HTTP/1.1
Host: www.myserver.com
Content-Type: application/json

{
    "sql": "select id, label, date_created from classifier_view"
}

Der Aufruf führt die Abfrage vollständig durch und antwortet mit den abgefragten Metadaten:

HTTP/1.1 200
Content-Type: text/csv
Content-Disposition: filename="Query.csv"

id,label,date_created
47ba9729-5cf4-4601-9405-cc2e9c528897,Akteur,2023-10-04T14:59:45.524
d6cb7df0-0b8f-4183-aa41-019252de17d2,Gruppe,2023-10-04T14:59:45.524
17aeeca2-9ab6-4cc0-ab28-b709e8c295f7,Zugehörigkeit,2023-10-04T14:59:45.524
52349fdd-9e14-4fa2-8f6c-4f70ac85a461,Organisation,2023-10-04T14:59:45.524

Im Fehlerfall (HTTP-Statuscode: 400) enthält die HTTP-Antwort eine Fehlermeldung:

HTTP/1.1 400
Content-Type: application/json

{
  "message": "FEHLER: keine Berechtigung für Tabelle classifier_view"
}

Metadata Query-API (asynchron)

Das Metadata Query-API kann mit der HTTP-Methode POST und der Option format aufgerufen werden, um Metadaten asynchron abzufragen. Mit den Optionen -H "Content-Type: application/json" und -d kann eine SQL-Anweisung <statement> in JSON eingebettet und in der HTTP-Nachricht (Request-Payload) übertragen werden.

curl -X POST -u <user>:<password> -H "Content-Type: application/json" -d "{\"sql\":\"<statement>\"}" "https://www.myserver.com/api/test/queries/download?format=<format>"

Der Aufruf startet einen Job und gibt die entsprechende Job-ID zurück. Der Job läuft im Hintergrund und stellt die abgefragten Metadaten im gewählten Format bereit. Der Status des Jobs kann mit der Job-ID gepollt werden. Wenn der Job fertig ist können die abgefragten Metadaten heruntergeladen sowie die Statistik und ein gegebenenfalls vorhandenes Protokoll abgefragt werden.

Beispiel: Metadaten abfragen (asynchron)

curl -X POST -u jdoe:s3cr3t -H "Content-Type: application/json" -d "{\"sql\":\"select * from classifier_view\"}" "https://www.myserver.com/api/test/queries/download?format=CSV"
curl -X POST -u jdoe:s3cr3t -H "Accept-Language: de" -H "Content-Type: application/json" -d "{\"sql\":\"select * from attribute_view\"}" "https://www.myserver.com/api/test/queries/download?format=JSON"

Beispiel: Ablauf und Fehlerbehandlung (asynchron)

Das Metadata Query-API wird mit der HTTP-Methode POST und der Option format=CSV aufgerufen, um Metadaten asynchron abzufragen. Mit den Optionen -H "Content-Type: application/json" und -d wird die SQL-Anweisung select id, label, date_created from classifier_view in JSON eingebettet und in der HTTP-Nachricht (Request-Payload) übertragen.

curl -X POST -u jdoe:s3cr3t -H "Content-Type: application/json" -d "{\"sql\":\"select id, label, date_created from classifier_view\"}" "https://www.myserver.com/api/test/queries/download?format=CSV"

POST /api/test/queries/download?format=CSV HTTP/1.1
Host: www.myserver.com
Content-Type: application/json

{
    "sql": "select id, label, date_created from classifier_view"
}

Der Aufruf startet einen Job und antwortet mit der Job-ID:

HTTP/1.1 200
Content-Type: application/json

{ "id":"90673f8b-bbf4-4379-a428-7feb8ff2a386" }

Mit der Job-ID kann der Status des Jobs gepollt werden:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/90673f8b-bbf4-4379-a428-7feb8ff2a386/statistics"

GET /api/test/jobs/90673f8b-bbf4-4379-a428-7feb8ff2a386/statistics HTTP/1.1
Host: www.myserver.com

Wenn der Job fertig ist (HTTP-Statuscode: 200), enthält die HTTP-Antwort den Status des Jobs COMPLETED und die Statistik:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "INFO",
      "message": "*Ergebnis Metadatenabfrage exportieren* erfolgreich (00:00:00)."
    },
    {
      "level": "INFO",
      "message": "4 Zeilen exportiert."
    }
  ],
  "status": "COMPLETED"
}

Im Fehlerfall enthält die HTTP-Antwort den Status des Jobs FAILED und die Statistik:

HTTP/1.1 200
Content-Type: application/json

{
  "messages": [
    {
      "level": "ERROR",
      "message": "*Ergebnis Metadatenabfrage exportieren* fehlgeschlagen (00:00:00)!"
    },
    {
      "level": "ERROR",
      "message": "1 *Fehler* aufgetreten!"
    }
  ],
  "status": "FAILED"
}

Die genaue Fehlerursache kann im Protokoll abgefragt werden:

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/90673f8b-bbf4-4379-a428-7feb8ff2a386/logs"

GET /api/test/jobs/90673f8b-bbf4-4379-a428-7feb8ff2a386/logs HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: application/json

{
  "totalCount": 1,
  "data": [
    {
      "level": "ERROR",
      "message": "FEHLER: keine Berechtigung für Tabelle classifier_view"
    }
  ]
}

Wenn der Job erfolgreich fertig ist, können die abgefragten Metadaten heruntergeladen werden.

curl -X GET -u jdoe:s3cr3t "https://www.myserver.com/api/test/jobs/90673f8b-bbf4-4379-a428-7feb8ff2a386/download"

GET /api/test/jobs/90673f8b-bbf4-4379-a428-7feb8ff2a386/download HTTP/1.1
Host: www.myserver.com

HTTP/1.1 200
Content-Type: text/csv
Content-Disposition: filename="Query.csv"

id,label,date_created
47ba9729-5cf4-4601-9405-cc2e9c528897,Akteur,2023-10-04T14:59:45.524
d6cb7df0-0b8f-4183-aa41-019252de17d2,Gruppe,2023-10-04T14:59:45.524
17aeeca2-9ab6-4cc0-ab28-b709e8c295f7,Zugehörigkeit,2023-10-04T14:59:45.524
52349fdd-9e14-4fa2-8f6c-4f70ac85a461,Organisation,2023-10-04T14:59:45.524

Metamodell​

Query-API​

Funktionsweise​

Optionen​

Option format​

Option language​

Option version​

HTTP-Methoden​

Aufruf​

Metadata Query-API (synchron)​

Beispiel: Metadaten abfragen (synchron)​

Beispiel: Ablauf und Fehlerbehandlung (synchron)​

Metadata Query-API (asynchron)​

Beispiel: Metadaten abfragen (asynchron)​

Beispiel: Ablauf und Fehlerbehandlung (asynchron)​

Metamodell

Query-API

Funktionsweise

Optionen

Option `format`

Option `language`

Option `version`

HTTP-Methoden

Aufruf

Metadata Query-API (synchron)

Beispiel: Metadaten abfragen (synchron)

Beispiel: Ablauf und Fehlerbehandlung (synchron)

Metadata Query-API (asynchron)

Beispiel: Metadaten abfragen (asynchron)

Beispiel: Ablauf und Fehlerbehandlung (asynchron)