API-Dokumentation - Data360_Govern - Neuheiten

Data360 Govern – Hilfe

Product type
Software
Portfolio
Verify
Product family
Data360
Product
Precisely Data Integrity Suite > Govern
Data360 Govern
Version
Neuheiten
Language
Deutsch
Product name
Data360 Govern
Title
Data360 Govern – Hilfe
Copyright
2024
First publish date
2014

Willkommen bei der Data360 Govern REST-API-Dokumentation.

Die Informationen in diesem Abschnitt werden zusammen mit der Swagger-API-Dokumentation bereitgestellt, in der Sie Abfragen testen und Details zu bestimmten Endpunkten anzeigen können. Sie können von der Anwendung aus auf die Swagger-Dokumentation zugreifen, indem Sie zu Verwaltung > Integration > API navigieren.

Die Data360 Govern-API ermöglicht Ihnen den Zugriff auf die Anwendung über Drittanbieter-Anwendungen und eine einfache Integration in Data360 Analyze und Data360 DQ+.

API-Übersicht

Versionsverwaltung

Die v1-API ist veraltet und wird in einer zukünftigen Version nicht mehr unterstützt. Verwenden Sie die v2-API, wenn möglich.

Die Anwendung wird über SNI (Servername Indication) gesichert. Sie müssen die SNI-Version 7.18.1 oder höher und mindestens TLS 1.0 verwenden.

Authentifizierung

Zur Authentifizierung müssen Sie Ihre API-Anmeldeinformationen im Anforderungsheader im folgenden Format angeben:

<API Key>;<API Secret>

Anfordern von API-Anmeldeinformationen

Data360 Govern generiert einen API-Schlüssel und einen geheimen API-Schlüssel für jeden Benutzer.

Sie können Ihre API-Anmeldeinformationen wie folgt abrufen:

  1. Melden Sie sich bei Data360 Govern an.
  2. Wählen Sie im Menü Profil oben rechts auf dem Bildschirm API-Schlüssel aus.
  3. Kopieren Sie den Wert aus dem Feld API-Schlüssel und speichern Sie ihn außerhalb der Anwendung.
  4. Kopieren Sie den Wert aus dem Feld Geheimer API-Schlüssel und speichern Sie ihn außerhalb der Anwendung. Sie müssen diese Werte für den Zugriff auf die API verwenden.
Anmerkung: Wenn Sie keinen Administratorzugriff haben, müssen Sie sich möglicherweise an Ihren Systemadministrator wenden, wenn die Option API-Schlüssel nicht im Benutzerprofilmenü angezeigt wird.

In einigen Fällen, beispielsweise bei der Integration in Data360 Analyze, können die für die Verbindung verwendeten API-Anmeldeinformationen die Anmeldeinformationen für ein Servicekonto sein, das speziell für Ihre Integration erstellt wurde. In diesem Fall wenden Sie sich an Ihren Precisely-Vertreter, um weitere Informationen zu erhalten.

Anmerkung: Die Verantwortungen, die Ihnen in der Anwendung zugewiesen wurden, gelten weiterhin, wenn Sie über die API auf Daten zugreifen. Daher verfügen Sie möglicherweise nicht über die erforderlichen Berechtigungen zum Anzeigen oder Bearbeiten eines Assets, auch wenn Sie die Authentifizierung erfolgreich durchgeführt haben.

Eine Anforderung stellen

Eine Anforderung besteht aus den folgenden Informationen:

  • Anforderungsheader - Bietet Informationen zum Client und Server, einschließlich Authentifizierungsinformationen und zulässiger Datenformate.
  • Methode - Definiert den Typ gewünschten Anforderung (GET, POST, PUT und DELETE).
  • Endpunkt - Gibt an, wie Sie auf die Ressource zugreifen.
  • Text - Ein Textkörper wird mit POST-, PUT- und DELETE-Anforderungen gesendet und enthält Informationen für den Server, beispielsweise Objektname, Felder und Feldwerte.

Zusätzlich enthalten einige Endpunkte optionale oder obligatorische Parameter, die zur weiteren Anpassung der API-Antwort verwendet werden.

Anmerkung: Das Standardformat für Anforderungen und Antworten ist JSON (application/json). Bei Parameternamen wird „CamelCase“ verwendet.

Anforderungsheader

Headerschlüssel Beschreibung
Autorisierung

Gibt die Authentifizierungsdaten an:

Authorization: <API Key>;<API Secret>

Inhaltstyp

Gibt das Format der Daten an:

Content-Type: application/json

Akzeptieren

Gibt das Datenformat an, das für die Antwort zulässig ist:

Accept: application/json

Sie können auch ein Workflow-Token im Feld Wert des Headers verwenden. Weitere Informationen finden Sie unter Erstellen eines Workflows, der eine externe API aufruft > Schritt 2 – Konfigurieren der HTTP-Anforderungsaktivität.

Methoden und Endpunkte

Endpunkte geben an, wie Sie auf die Ressource zugreifen, und die HTTP-Anforderungsmethode definiert den Typ der Anforderung.

Die Data360 Govern-API verwendet zum Senden von Anforderungen die folgenden Standardmethoden:

Methode Aktion
GET Ruft Ressourcen ab
POST Erstellt Ressourcen
PUT

Aktualisiert vorhandene Ressourcen

DELETE Löscht Ressourcen

In einigen Fällen können PUT-Anforderungen auch zum Erstellen von Ressourcen verwendet werden. Zum Beispiel kann der PUT-Endpunkt api/v2/fields verwendet werden, um Feldtypen hinzuzufügen oder zu aktualisieren. Details zu einer bestimmten PUT-Anforderung finden Sie in der Endpunkt-Übersicht in Swagger, z. B.:

Swagger-API-Dokumentation

Jede Ressource verfügt über eine Vielzahl von zugehörigen Endpunkten. Der Endpunkt zeigt den Endpfad einer Ressourcen-URL an, und der Basispfad ist für alle Endpunkte gleich. Beispiel:

https://example.data3sixty.com/api/v2/assets/types

Anforderungstext

Auf der Swagger-Benutzeroberfläche enthält jede API-Methode, die einen Anforderungstext erfordert, eine Beispielvorlage, die Sie als Ausgangspunkt verwenden und dann ändern können, um Ihre Anforderung ordnungsgemäß zu erstellen.

Der POST-Endpunkt /api/v2/metrics/resultsbeispielsweise verfügt über einen obligatorischen Anforderungstext, für den Sie auf eine Asset-UID und eine Metrik-Asset-UID verweisen müssen:

[ { 	"AssetUid": "b1c4f830-c71c-4f95-909d-a1d67ca5361c", 	"MetricAssetUid": "d06f201c-4241-4102-8d68-07d4fb37dfc1", 	"EffectiveDate": "2019-05-08T08:51:56.737Z", 	"Result": true } ]

In Swagger wird der Anforderungstext wie folgt angezeigt:

Anforderungstext

Klicken Sie rechts auf dem Bildschirm auf die Beispielvorlage, um den Modellparameter links auszufüllen. Geben Sie anschließend die tatsächlichen UID-Werte ein, die den Platzhaltertext ersetzen sollen (00000000-0000-0000-0000-000000000000).

Sie müssen alle erforderlichen Felder in den Anforderungstext einschließen, beispielsweise beim Erstellen eines neuen Assets über eine POST-Anforderung. Optionale Felder können gelöscht werden, wenn kein zu sendender Wert vorhanden ist.

Bei einigen Anforderungen, z. B. Batch-Anforderungen für große Datenmengen, können Sie einen optionalen Parameter einfügen, um zu verfolgen, ob das Asset erfolgreich hinzugefügt oder aktualisiert wurde, oder ob dies fehlgeschlagen ist.

Parameter

Zusätzlich enthalten einige Endpunkte optionale oder obligatorische Parameter, die zur weiteren Anpassung der API-Antwort verwendet werden.

Parametertyp Beschreibung Beispiel
Pfad Parameter, die im Pfad des Endpunktes enthalten sind, werden normalerweise in geschweiften Klammern angegeben.

Der GET-Endpunkt /api/v2/assets/fields/{assetTypeUid} enthält einen obligatorischen Pfadparameter, z. B.:

https://example-igx.preview.data3sixty.com/api/v2/assets/fields/188f094b-fb02-4de3-8790-8c0d32d98e1a

Abfrage Parameter, die in der Abfragezeichenfolge eines Endpunktes nach dem Zeichen '?' enthalten sind.

Der GET-Endpunkt /api/v2/fields verfügt über eine Reihe optionaler Abfrageparameter. Im folgenden Beispiel werden die Parameter Type und _pageSize verwendet, um anzugeben, dass die Antwort nur boolesche Felder enthalten und die Anzahl der Ergebnisse pro Seite auf 100 beschränkt werden soll:

https://example.data3sixty.com/api/v2/fields?Type=Boolean&_pageSize=100

Details zu bestimmten Parametern finden Sie auf der Seite mit der Swagger-API-Dokumentation.

Beispielanforderung

In den Beispiel-API-Anforderungen in diesem Abschnitt der Hilfe wird die Curl-Syntax verwendet, um alle erforderlichen Informationen, einschließlich Anforderungsheadern, Methoden, Endpunkten und Daten, sowie alle obligatorischen und optionalen Parameter anzuzeigen:

         curl -X GET --header 'Accept: application/json' --header 'Authorization: key;secret' 'https://example.data3sixty.com/api/v2/assets/types'       

Curl bietet eine Bibliothek und ein Befehlszeilentool für die Übertragung von Daten auf Server mithilfe verschiedener Standardprotokolle wie HTTPS.

Anmerkung: Unter Windows müssen Sie einfache Anführungszeichen durch doppelte Anführungszeichen ersetzen.

Im folgenden Beispiel werden die Header-Informationen für dieselbe Anforderung angezeigt, die bei der Verbindung mit der Data360 Govern-API über einen API-Client verwendet wird:

GET https://example.data3sixty.com/api/v2/assets/types HTTP/1.1 	Authorization: <API Key>;<API Secret> 	Content-Type: application/json 	Accept: application/json

Evaluierung der Antwort

Antwortcodes

HTTP-Statuscode Beschreibung Fehlersuche
200

Kennzeichnet eine erfolgreiche Ausführung.

N/A
400

Kennzeichnet einen Fehler aufgrund einer ungültigen Anforderung.

Überprüfen Sie, ob Sie die Kennung (UID) in Ihrer Anforderung korrekt formatiert haben.
401 Kennzeichnet einen Authentifizierungsfehler.

Überprüfen Sie, ob der Anforderungs-Header die erforderlichen Authentifizierungsdaten enthält.

Wenn Sie weiterhin Probleme haben, haben Sie möglicherweise nicht die erforderliche Berechtigung, die Ressource basierend auf den Ihnen in der Anwendung zugewiesenen Verantwortungen anzuzeigen oder zu bearbeiten.

403 Kennzeichnet einen „Zugriff verweigert“-Fehler. Möglicherweise haben Sie nicht die erforderliche Berechtigung, die Ressource basierend auf den Ihnen in der Anwendung zugewiesenen Verantwortungen anzuzeigen oder zu bearbeiten.
404 Kennzeichnet, dass die angeforderte Ressource nicht gefunden wurde. Überprüfen Sie, ob Sie die Kennung (UID) in Ihrer Anforderung korrekt formatiert haben.
406 Kennzeichnet, dass die Anforderung nicht den erforderlichen Parametertyp oder die erforderlichen Felder enthält. Überprüfen Sie, ob alle erforderlichen Parametertypen und -felder einbezogen wurden.
409 Kennzeichnet, dass die angeforderte Ressource bereits existiert. N/A
500 Kennzeichnet, dass während der Verarbeitung der Anforderung ein unbekannter Fehler aufgetreten ist. N/A

Beispielantwort

HTTP/1.1 200 OK "content-length": "2", "content-type": "application/json; charset=utf-8"  [ 	{ 		"uid": "85315000-c77f-4898-84db-f4872cbd2dc0", 		"Name": "Bloomberg", 		"Description": "Metadata via the Bloomberg Fields CSV file and other Bloomberg sources.", 		"Class": { 			"ID": 3, 			"Name": "Technical Asset", 			"Description": "Technical assets." 		}, 		"Path": "Bloomberg" 	}, 	{ 		"uid": "88e6e59c-0cd8-49a9-a4f4-059b7172ddee", 		"Name": "Business Calendar", 		"Class": { 			"ID": 4, 			"Name": "Technical Asset", 			"Description": "Technical assets." 		}, 		"Path": "Business Calendar" 	} ]
Tipp: In diesem Beispiel enthält das erste Element eine „Beschreibung“-Eigenschaft, die Eigenschaft „Beschreibung“ wird jedoch im zweiten Element nicht zurückgegeben. Wenn in einem Asset benutzerdefinierte Felder vorhanden sind, kommt es häufig vor, dass der Feldname und der Feldwert in der Antwort nur angezeigt werden, wenn das Feld ausgefüllt wurde. Beachten Sie, dass diese Verhaltensweise nicht von der Konfiguration des Feldes Anzeigen, wenn leer in der Anwendung beeinflusst wird.

Häufige Anwendungsfälle

Mit der Data360 Govern-API können Sie Informationen zu den Assets in Ihrer Data-Governance-Anwendung abrufen.

Zu den typischen Anwendungsfällen gehören:

  • Abrufen von Informationen über vorhandene Assets in Ihrem Data-Governance-System, einschließlich der Details zu Beziehungen und Eigentum.
  • Hinzufügen von technischen Metadaten aus externen Datenquellen, um Kontext für Ihre Business-Assets bereitzustellen.
  • Anwenden der Bewertung auf Ihre Data-Governance-Assets (siehe Verwenden der API, um eine Bewertung auf Assets anzuwenden).
  • Unterstützung von technischen Ressourcen in Ihrem Business-Glossar

Hinweise und Tipps

Hinweis Beschreibung

Endpunkte für Batch-Verarbeitung

Wenn Sie mit einer großen Anzahl von Elementen arbeiten, sollten Sie die „Batch“-Endpunkte verwenden.

Wenn ein „Batch“-Endpunkt vorhanden ist, hat das Nicht-Batch-Äquivalent häufig eine Begrenzung auf 250 Elemente. Die „Batch“-Endpunkte sind für eine größere Anzahl von Elementen vorgesehen, da sie die Elementliste für eine asynchrone oder Batch-Verarbeitung speichern.

Sie können beispielsweise die folgenden Endpunkte verwenden, um eine Reihe von Assets basierend auf der eindeutigen ID des Asset-Typs zu entfernen. Der erste ist für eine geringere Anzahl von Elementen vorgesehen, und der zweite dient der Verarbeitung einer größeren Anzahl von Elementen:

  • DELETE /api/v2/assets/{assetTypeUid} - Verwenden Sie diesen Endpunkt, wenn Sie weniger als 250 Elemente verarbeiten möchten und sofort Ergebnisse benötigen.
  • DELETE /api/v2/assets/batch/{assetTypeUid} - Verwenden Sie diesen Endpunkt, wenn Sie eine größere Anzahl von Elementen verarbeiten.
Anmerkung: Es wird empfohlen, die Swagger-Benutzeroberfläche für große Anforderungen nicht zu verwenden. Für die Verarbeitung von größeren Anforderungen sollten Sie einen alternativen API-Client verwenden.
Anmerkung: Jede Umgebung ist auf zwei Batch-Anforderungen gleichzeitig beschränkt.
Anmerkung: Die Ausführungsreihenfolge von Batch-API-Aufrufen entspricht nicht der Reihenfolge, in der die Aufträge übermittelt wurden. Wenn Sie beispielsweise zehn Batchaufträge innerhalb von 30 Sekunden übermitteln, werden die Aufträge nicht unbedingt in der Reihenfolge ausgeführt, in der sie übermittelt wurden.

Seitengröße

Es gibt keine maximale Seitengröße. Es wird jedoch empfohlen, die Seitengröße entsprechend der Größe Ihrer Abfrage einzugrenzen. Wenn Sie beispielsweise den GET-Endpunkt /api/v2/assets/{assetTypeUid} verwenden, wird empfohlen, die Seitengröße entsprechend der Menge des aufgerufenen Inhalts auf 1.000 oder weniger zu begrenzen.

Sie können den Parameter _pageSize verwenden, um die Anzahl der Ergebnisse zu beschränken, die pro Seite zurückgegeben werden. Der Standardwert ist 200.

JSON-Eigenschaften

Aufgrund der Art und Weise, wie der JSON-Serializer Daten verarbeitet, gibt es keine Garantie dafür, dass die Eigenschaft angezeigt wird, wenn der Wert null ist. Ebenso ist die Reihenfolge der zurückgegebenen Eigenschaften nicht immer gleich.

X-HTTP-Method-Override-Header

Um eine POST-Anforderung mit einem Text zu vermeiden, können Sie X-HTTP-Method-Override: DELETE im Anforderungsheader verwenden. Zum Beispiel beim Löschen von Beziehungen in Data360 Govern über einen Konnektor.

Asset-Schlüsselfelder

Wenn Sie eine Aktualisierung (eine PUT-Anforderung) ausführen, sucht die API mithilfe der angegebenen Asset-UID nach allen Schlüsselfeldwerten. Sie erhalten einen Fehler, wenn für den angegebenen Asset-Typ ein Schlüsselfeld definiert ist und Assets vorhanden sind, die einen NULL-Wert für dieses Feld aufweisen.

Asset-Links

Sie können über den folgenden Link auf ein beliebiges Asset zugreifen, wobei <environment> durch Ihren Data360-Host und <asset uid> durch den UID-Wert eines Assets ersetzt wird:

https://<environment>.data3sixty.com/asset/<asset uid>

Beispiel:

https://example.data3sixty.com/asset/5f2692c7-6d64-4e23-9a11-faa69a7f35de

Sie können über den folgenden Link auf die Liste der Asset-Typen für Business-Assets, technische Assets, Modell-Assets oder Regel-Assets zugreifen, wobei <environment> durch Ihren Data360-Host und <asset type uid> durch den UID-Wert eines Asset-Typs ersetzt wird:

https://<environment>.data3sixty.com/assets/<asset type uid>

Beispiel:

https://example.data3sixty.com/assets/188f094b-fb02-4de3-8790-8c0d32d98e1a