API-documentatie - Data360_Govern - Nieuwste

Help Data360 Govern

Product type
Software
Portfolio
Verify
Product family
Data360
Product
Data360 Govern
Precisely Data Integriteit Suite > Govern
Version
Nieuwste
Language
Nederlands
Product name
Data360 Govern
Title
Help Data360 Govern
Copyright
2023
First publish date
2014

Welkom bij de Data360 Govern REST API-documentatie.

De informatie in dit gedeelte wordt in combinatie met de Swagger API-documentatie verstrekt, waar u query's kunt testen en details van specifieke eindpunten kunt bekijken. U kunt vanuit de toepassing toegang krijgen tot de documentatie van Swagger door te navigeren naar Beheer > Integratie > API.

Met de Data360 Govern API hebt u toegang tot de toepassing via externe toepassingen en kunt u deze eenvoudig integreren met Data360 Analyze en Data360 DQ+.

API-overzicht

Versiebeheer

De v1 API is afgeschaft en wordt niet ondersteund in een toekomstige release. Gebruik waar mogelijk de v2 API.

De toepassing wordt beveiligd via SNI (Server Name Indication). U moet SNI versie 7.18.1 of hoger en ten minste TLS 1.0 gebruiken.

Verificatie

Voor verificatie moet u uw API-inloggegevens in de aanvraagheader opgeven in de volgende indeling:

<API Key>;<API Secret>

API-inloggegevens ophalen

Data360 Govern genereert een API-sleutel en een API-geheim voor elke gebruiker.

U kunt uw API-inloggegevens als volgt ophalen:

  1. Meld u aan bij Data360 Govern.
  2. Ga naar het menu Profiel rechtsboven in het scherm en selecteer API-sleutel.
  3. Kopieer de waarde uit het veld API-sleutel en sla de waarde op buiten de toepassing.
  4. Kopieer de waarde uit het veld API-geheim en sla de waarde op buiten de toepassing. U dient deze waarden te gebruiken om toegang te krijgen tot de API.
Opmerking: Als u geen beheerderstoegang hebt, moet u mogelijk contact opnemen met uw systeembeheerder als de optie API-sleutel niet zichtbaar is in uw gebruikersprofielmenu.

In sommige gevallen, bijvoorbeeld bij integratie met Data360 Analyze, kunnen de API-inloggegevens die worden gebruikt om verbinding te maken de inloggegevens zijn voor een serviceaccount dat specifiek is gemaakt voor uw integratie. In dat geval neemt u voor meer informatie contact op met de Precisely-vertegenwoordiger.

Opmerking: De verantwoordelijkheden die in de toepassing aan u zijn toegewezen, blijven van toepassing wanneer u gegevens via de API opent. Daarom hebt u mogelijk niet de vereiste rechten om een asset te bekijken of te bewerken, ook als u zich hebt geverifieerd.

Een aanvraag indienen

Een aanvraag bestaat uit de volgende gegevens:

  • Aanvraagheaders - Geef informatie op aan de client en de server, met inbegrip van verificatiegegevens en geaccepteerde gegevensindelingen.
  • Methode - Hiermee wordt het type aanvraag gedefinieerd (GET, POST, PUT en DELETE).
  • Eindpunt - Geeft aan hoe u toegang krijgt tot de resource.
  • Hoofdtekst - Er wordt een hoofdtekst verzonden met de aanvragen POST, PUT en DELETE. De hoofdtekst bevat informatie voor de server waarop deze moet reageren, bijvoorbeeld de objectnaam, velden en veldwaarden.

Daarnaast bevatten sommige eindpunten ook optionele of verplichte parameters die worden gebruikt om het API-antwoord verder aan te passen.

Opmerking: De standaardindeling voor aanvragen en antwoorden is JSON (toepassing/json). Parameternamen maken gebruik van camelCase.

Aanvraagheaders

Headersleutel Beschrijving
Autorisatie

Geeft de verificatiereferenties op:

Authorization: <API Key>;<API Secret>

Inhoudstype

Geeft de indeling van de gegevens aan:

Content-Type: application/json

Accepteren

Geeft de gegevensindeling aan die acceptabel is voor het antwoord:

Accept: application/json

U kunt een workflowtoken ook gebruiken in het veld Waarde van de header. Zie Een workflow maken die een externe API aanroept > Stap 2 - Configureer de activiteit HTTP-request voor meer informatie.

Methoden en eindpunten

Eindpunten geven aan hoe u toegang krijgt tot de resource en de HTTP-requestmethode definieert het type aanvraag dat moet worden ingediend.

De Data360 Govern API maakt gebruik van de volgende standaardmethoden om aanvragen in te dienen:

Methode Actie
GET Hiermee worden resources opgehaald
POST Hiermee worden resources gemaakt
PUT

Hiermee worden bestaande resources bijgewerkt

VERWIJDEREN Hiermee worden resources verwijderd

In sommige gevallen kunnen PUT-aanvragen ook worden gebruikt om resources te maken. Het eindpunt PUT api/v2/fields kan bijvoorbeeld worden gebruikt voor het toevoegen of bijwerken van veldtypen. Zie voor de details van een specifieke PUT-aanvraag de samenvattingsgegevens van de eindpunten in Swagger, bijvoorbeeld:

Swagger API-documentatie

Elke resource heeft een reeks verwante eindpunten. Het eindpunt geeft het eindpad van een resource-URL weer en het basispad is algemeen voor alle eindpunten, bijvoorbeeld:

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

Aanvraagtekst

In de Swagger-gebruikersinterface bevat elke API-methode waarvoor een aanvraagtekst nodig is een voorbeeldsjabloon die u kunt gebruiken als beginpunt en die u vervolgens kunt wijzigen om aan de behoeften van uw aanvraag te voldoen.

Het eindpunt POST /api/v2/metrics/results bevat bijvoorbeeld een verplichte aanvraagtekst die vereist dat u verwijst naar een asset-UID en een metrische asset-UID:

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

In Swagger wordt de aanvraagtekst als volgt weergegeven:

Aanvraagtekst

Klik op de voorbeeldsjabloon aan de rechterkant van het scherm om de modelparameter aan de linkerkant in te vullen en voer vervolgens de werkelijke UID-waarden in om de tekst van tijdelijke aanduiding te vervangen (00000000-0000-0000-0000-000000000000).

U moet vereiste velden in de aanvraagtekst opnemen, bijvoorbeeld wanneer u een nieuwe asset maakt via een POST-aanvraag. Optionele velden kunnen worden verwijderd als er geen waarde is om te verzenden.

Voor sommige aanvragen, bijvoorbeeld batchaanvragen voor grote hoeveelheden gegevens, kunt u een optionele parameter opnemen om bij te houden of de asset is toegevoegd of bijgewerkt.

Parameters

Sommige eindpunten bevatten ook optionele of verplichte parameters die worden gebruikt om het API-antwoord verder aan te passen.

Parametertype Beschrijving Voorbeeld
Pad Parameters die zijn opgenomen in het pad van het eindpunt, meestal tussen accolades.

Het eindpunt GET /api/v2/assets/fields/{assetTypeUid} bevat een verplichte padparameter, bijvoorbeeld:

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

Query Parameters die zijn opgenomen in de queryreeks van een eindpunt, voorafgegaan door een ?-teken.

Het eindpunt GET /api/v2/fields bevat een aantal optionele queryparameters. In het volgende voorbeeld worden de parameters Type en _pageSize gebruikt om aan te geven dat het antwoord alleen velden van het Boolean-type mag bevatten en dat het aantal resultaten per pagina moet worden beperkt tot 100:

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

U kunt details van specifieke parameters vinden op de pagina Swagger API-documentatie.

Voorbeeldaanvraag

Voor voorbeelden van API-aanvragen in dit gedeelte helpt de Curl-syntaxis om alle vereiste informatie weer te geven, inclusief aanvraagheaders, methoden, eindpunten en gegevens, alsmede verplichte en optionele parameters:

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

Curl biedt een bibliotheek en een opdrachtregelprogramma voor het overdragen van gegevens naar servers met behulp van verschillende standaardprotocollen zoals HTTPS.

Opmerking: In Windows moet u de enkele aanhalingstekens vervangen door dubbele aanhalingstekens.

In het volgende voorbeeld wordt de headerinformatie weergegeven voor dezelfde aanvraag voor gebruik bij het verbinden met de Data360 Govern API via een API-client:

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

Het antwoord evalueren

Responscodes

HTTP statuscode Beschrijving Probleemoplossing
200

Geeft aan dat iets is gelukt.

N.v.t
400

Geeft een fout aan vanwege een ongeldige aanvraag.

Controleer of u de ID (UID) in uw aanvraag juist hebt opgemaakt.
401 Geeft een verificatiefout aan.

Controleer of uw aanvraagheader de vereiste verificatiegegevens bevat.

Als u nog steeds problemen ondervindt, is het mogelijk dat u niet over de vereiste rechten beschikt om de resource te bekijken of te bewerken op basis van de verantwoordelijkheden die in de toepassing aan u zijn toegewezen.

403 Geeft de fout 'Toegang geweigerd' aan. Het is mogelijk dat u niet over de vereiste rechten beschikt om de resource te bekijken of te bewerken op basis van de verantwoordelijkheden die in de toepassing aan u zijn toegewezen.
404 Geeft aan dat de aangevraagde resource niet is gevonden. Controleer of u de ID (UID) in uw aanvraag juist hebt opgemaakt.
406 Geeft aan dat de aanvraag niet het vereiste parametertype of de vereiste velden bevat. Controleer of u alle vereiste parametertypen en velden hebt opgenomen.
409 Geeft aan dat de aangevraagde resource al bestaat. N.v.t
500 Geeft aan dat er een onbekende fout is opgetreden tijdens het verwerken van de aanvraag. N.v.t

Voorbeeldantwoord

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" 	} ]
Tip: In dit voorbeeld bevat het eerste item een eigenschap 'Beschrijving', maar de eigenschap 'Beschrijving' wordt niet in het tweede item geretourneerd. In veel gevallen, als er aangepaste velden voor een asset zijn, worden de veldnaam en waarde mogelijk alleen weergegeven in het antwoord als het veld is ingevuld. Let erop dat dit gedrag niet wordt beïnvloed door de veldconfiguratie Weergeven indien leeg in de toepassing.

Veelvoorkomende gebruiksscenario's

Met de Data360 Govern API kunt u informatie verkrijgen over de assets in uw toepassing voor data governance.

Veelvoorkomende gebruiksscenario's zijn onder meer:

  • Informatie ophalen over bestaande assets in uw systeem voor data governance, inclusief details over relaties en eigenaarschap.
  • Technische metadata toevoegen vanuit externe gegevensbronnen om uw bedrijfsassets een context te bieden.
  • Scores toepassen op uw data governance-assets (zie De API gebruiken om scores toe te passen op uw assets).
  • Technical assets promoten in uw bedrijfswoordenlijst.

Hints en tips

Hint Beschrijving

Eindpunten voor batchverwerking

Wanneer u met een groot aantal items werkt, wordt aanbevolen om gebruik te maken van batch-eindpunten.

Wanneer er een batch-eindpunt is, heeft het niet-batch equivalent vaak een limiet van 250 items. De batch-eindpunten zijn bedoeld voor een groter aantal items, omdat ze de itemlijst opslaan voor asynchrone of batchverwerking.

U kunt bijvoorbeeld gebruikmaken van de volgende eindpunten om een reeks assets te verwijderen op basis van de opgegeven unieke assettype-ID. Het eerste is bedoeld voor een kleiner aantal items en het tweede voor het verwerken van een groter aantal items:

  • DELETE /api/v2/assets/{assetTypeUid} - Gebruik dit eindpunt als u minder dan 250 items wilt verwerken en direct resultaten wilt.
  • DELETE /api/v2/assets/batch/{assetTypeUid} - Gebruik dit eindpunt wanneer u een groter aantal items verwerkt.
Opmerking: Het wordt aanbevolen om de Swagger-gebruikersinterface niet te gebruiken bij grote aanvragen. Het wordt aanbevolen om voor het afhandelen van grotere aanvragen een alternatieve API-client te gebruiken.
Opmerking: Elke omgeving is beperkt tot twee batchaanvragen tegelijk.
Opmerking: De volgorde van uitvoering van batch-API-aanroepen is niet gegarandeerd de volgorde waarin de taken zijn ingediend. Als u bijvoorbeeld binnen 30 seconden tien batchtaken indient, worden de taken niet noodzakelijkerwijs uitgevoerd in de volgorde waarin ze zijn ingediend.

Paginagrootte

Er is geen maximale paginagrootte. Het wordt echter aanbevolen om de paginagrootte te beperken op basis van de grootte van uw query. Wanneer u bijvoorbeeld het eindpunt GET /api/v2/assets/{assetTypeUid} gebruikt, wordt aanbevolen om de paginagrootte te beperken tot 1000 of minder, afhankelijk van de hoeveelheid inhoud die u aanroept.

U kunt de parameter _pageSize gebruiken om het aantal resultaten per pagina te beperken. De standaardwaarde is 200.

JSON-eigenschappen

Vanwege de manier waarop de JSON-serializer gegevens verwerkt, is er geen garantie dat de eigenschap wordt weergegeven wanneer de waarde null is. In vergelijkbare gevallen is de volgorde van de eigenschappen die worden geretourneerd niet altijd hetzelfde.

Kop X-HTTP-Method-Override

Om te voorkomen dat een POST-aanvraag met een hoofdtekst wordt ingediend, kunt u X-HTTP-Method-Override: DELETE in de aanvraagheader gebruiken. Bijvoorbeeld wanneer relaties in Data360 Govern worden verwijderd via een connector.

Assetsleutelvelden

Wanneer u een update (een PUT-aanvraag) uitvoert, zoekt de API alle sleutelveldwaarden op met behulp van de opgegeven asset-UID. U krijgt een foutmelding als er voor het opgegeven assettype een sleutelveld is gedefinieerd en er assets zijn met een null-waarde voor dit veld.

Assetkoppelingen

Elke asset kan worden geopend via de volgende koppeling, waarbij <environment> wordt vervangen door uw Data360-host en <asset uid> wordt vervangen door de UID-waarde van een asset:

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

Bijvoorbeeld:

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

U kunt via de volgende koppeling toegang krijgen tot de lijst met assettypen voor bedrijfsassets, technische assets, modelassets of regelassets, waar <environment> wordt vervangen door uw Data360-host en <asset type uid> wordt vervangen door de UID-waarde van een assettype:

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

Bijvoorbeeld:

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