Brug af Postman til at interagere med CluedIn API

CluedIn tilbyder et kraftfuldt sæt af REST- og GraphQL-API'er. Du kan bruge dem til at indlæse data i CluedIn, eksportere data fra CluedIn, migrere konfiguration osv. Da CluedIn er en webapplikation med web-UI (klient) og API (server), kan du via API gøre alt, hvad du kan gøre via UI.

Alt, hvad vi gør i denne artikel, kan gøres i ethvert programmeringssprog, kommandolinjeværktøjer som curl og wget, UI-apps som Insomnia eller Nightingale og mange andre. Vi bruger dog Postman, som sandsynligvis er det mest populære værktøj til at arbejde med API'er.

Så lad os starte en CluedIn-instans, åbne Postman og begynde.

Opsætning af environment

Først har vi selvfølgelig brug for en CluedIn-instans. Min er på: https://foobar.172.167.52.102.sslip.io/.

Hvis vi ser på denne URL, er subdomænet foobar et såkaldt "organisationsnavn" — du skal kende det, fordi man teknisk set kan have flere "organisationer" konfigureret på den samme CluedIn-instans, så brugere, indstillinger og data fra en organisation er isoleret fra en anden.

172.167.52.102.sslip.io-delen er hoveddomænet for din CluedIn-instans, som du automatisk får, når du installerer CluedIn fra Azure Marketplace. (Du kan selvfølgelig konfigurere det til dit eget domæne, f.eks. mdm.contoso.com)

I Postman kan du nu oprette din egen collection eller importere den, jeg bruger dagligt: https://github.com/romaklimenko/cluedin/blob/main/postman/CluedIn.postman_collection.json.

I næste trin opretter vi et nyt Environment, der gemmer domæne- og legitimationskonfigurationen. Hvis du bruger skabelonen herfra: https://github.com/romaklimenko/cluedin/blob/main/postman/CluedIn-%20Home.postman_environment.json, skal du kun ændre et par ting:

• domain — i mit tilfælde er det 172.167.52.102.sslip.io.
• org_name — organisationsnavn, foobar i mit tilfælde.
• protocol — skal være https, medmindre du kører CluedIn i Docker på din lokale maskine.
• org_name — foobar i mit tilfælde.
• user_email og password — naturligvis e-mail og adgangskode. Nogle API'er kræver et access token genereret for en brugerkonto, men nogle kan fungere med API tokens, du kan generere i UI. For sidstnævnte kan du springe e-mail- og adgangskodekonfigurationen over.

Til sidst indeholder environmentet nogle foruddefinerede URL'er:

• org_url: {{protocol}}://{{org_name}}.{{domain}} - bliver til https://foobar.172.167.52.102.sslip.io - vi genbruger denne URL til at bygge enhver CluedIn API-URL, vi har brug for.
• auth_url: {{org_url}}/auth - transformeres til https://foobar.172.167.52.102.sslip.io/auth - bruges til at logge ind med e-mail og adgangskode, oprette brugere osv.
• api_url: {{org_url}}/api/api - transformeres til https://foobar.172.167.52.102.sslip.io/api/api - hvor de fleste API'er befinder sig.
• graphql_api_url: {{api_url}}/graphql - https://foobar.172.167.52.102.sslip.io/api/api/graphql GraphQL-endpointet, du kan bruge til at eksportere data fra CluedIn. Dette endpoint fungerer med et API token, du kan generere i CluedIn UI.
• graphql_url: {{org_url}}/graphql - https://foobar.172.167.52.102.sslip.io/graphql - GraphQL-endpointet, der bruges til UI-operationer. Dette endpoint fungerer ikke med API tokens - du skal bruge din brugers access token.

Hent et token

Vi har Postman-environmentet; lad os prøve at "logge ind" med Postman, dvs. kalde API'et for at få brugerens access token.

For at gøre det, kald "Get a Token"-endpointet:

Tillykke! Requesten er vellykket. Og hvis du tjekker environmentet nu, vil du finde et par nye variabler tilføjet automatisk:

• access_token — JWT-tokenet til at tilgå CluedIn API.
• refresh_token — tokenet du kan bruge til at forny access token.
• org_id — en speciel identifikator for tokenets kontekst, der bruges i nogle kald, så du ikke behøver at hente den separat.

Kald CluedIn API'er

Nu kan du kalde CluedIn API'er. Prøv for eksempel at kalde "Get Schema" for at få den fulde liste over CluedIn Vocabulary keys og deres mappings:

Konklusion

For at opsummere og give et par anbefalinger:

• Alt hvad du kan gøre via CluedIn UI, kan du automatisere ved at kalde API'er.
• For at udforske, hvordan en API-request sendes fra UI, brug Network-fanen i din browser og en udvidelse som GraphQL Network Inspector.
• CluedIn Documentation Portal opdateres regelmæssigt — der er masser af nyttig information der.