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 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+.
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:
- Melden Sie sich bei Data360 Govern an.
- Wählen Sie im Menü Profil oben rechts auf dem Bildschirm API-Schlüssel aus.
- Kopieren Sie den Wert aus dem Feld API-Schlüssel und speichern Sie ihn außerhalb der Anwendung.
- 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.
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.
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.
Anforderungsheader
| Headerschlüssel | Beschreibung |
|---|---|
| Autorisierung |
Gibt die Authentifizierungsdaten an: |
| Inhaltstyp |
Gibt das Format der Daten an: |
| Akzeptieren |
Gibt das Datenformat an, das für die Antwort zulässig ist: |
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.:
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:
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 |
| Abfrage | Parameter, die in der Abfragezeichenfolge eines Endpunktes nach dem Zeichen '?' enthalten sind. |
Der GET-Endpunkt |
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.
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/jsonEvaluierung 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" } ]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:
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 Sie können den Parameter |
|
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 |
|
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 Beispiel: 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 Beispiel: |