Oorspronkelijk gepubliceerd op 20 februari 2019
Houd er rekening mee dat Postman een ontwikkelingstool van derden is. D2L raadt u aan om de geschiktheid van Postman binnen uw organisatie te beoordelen voordat u het gebruikt.
D2L en integratiestandaarden
Bij D2L zijn en blijven we grote voorstanders van integratiestandaarden. Eind 2016 hebben we OAuth 2.0-ondersteuning toegevoegd voor de ontwikkeling van Brightspace API-apps. OAuth 2.0 is een open standaard authenticatieframework dat meerdere authenticatiestromen biedt, waaronder de driepotige OAuth-flow. Het stelt ontwikkelaars in staat om namens een gebruiker applicaties te schrijven die toegang hebben tot verschillende services.
Houd er rekening mee dat we ons Id/Key Pair-authenticatiemodel blijven ondersteunen, maar dat onze focus zal liggen op voortdurende ondersteuning en groei van OAuth 2.0. Een voorbeeld hiervan is een recente update die we hebben doorgevoerd in onze OAuth 2.0-implementatie. In onze productrelease van maart 2019 hebben we ondersteuning toegevoegd voor De parameter Client_ID aanvraag gebruiken om zichzelf te identificeren bij het verzenden van aanvragen naar het token-eindpunt. We hopen dat veel Brightspace-ontwikkelaars baat zullen hebben bij deze update.
Waarom hebben we deze update uitgevoerd?
De opname van de Client_ID-waarde heeft geen invloed op bestaande OAuth 2.0-apps. Behalve dat we meer trouw zijn aan de standaard, hoorden we via de ontwikkelaarsgemeenschap van onze klanten dat onze OAuth 2.0-implementatie niet compatibel was met sommige API-tools van derden. Meer specifiek konden Brightspace-ontwikkelaars Postman niet gebruiken met de Brightspace API, omdat deze de Client_ID-waarde bevatte in het verzoek om een op OAuth 2.0 gebaseerde interactie uit te voeren.
Wat is postbode?
Postman is de marktleidende API-testtool. Het is beschikbaar om te downloaden op www.getpostman.com.
Postman is zowel krachtig als gebruiksvriendelijk en zijn Ondersteuningscentrum is erg nuttig. Van de vele functies denken we dat het volgende zeer nuttig zal zijn voor Brightspace API-ontwikkelaars:
- Creëer ontwikkelomgevingen (bijvoorbeeld één voor je Brightspace-testlocatie en één voor je productielocatie)
- Creëer omgevingsvariabelen (bijv. Brightspace Domain, API-versie)
- Maak verzamelingen die de mogelijkheid bieden om meerdere API-aanroepen achter elkaar uit te voeren
- JavaScript gebruiken om variabelen door te geven aan een API-aanroep
- JavaScript gebruiken om variabelen op te slaan na een API-aanroep
Aan de slag met een Brightspace OAuth 2.0 App
Voor het gebruik van Postman met Brightspace is een Brightspace OAuth 2.0-app vereist. Als u nog geen OAuth 2.0-app hebt, kunt u er een maken in uw exemplaar van Brightspace door te navigeren naar Aan de slag met OAuth 2.0, of gebruik de openbare app in de Brightspace-ontwikkelomgeving (zorg ervoor dat u lid wordt van de ontwikkelaarsgroep om toegang te krijgen tot het bestand 'Developer Instance Credentials', dat de details van de openbare OAuth 2.0-app bevat).
Een Postman Collection maken en koppelen aan Brightspace
Voordat u begint, moet u ervoor zorgen dat u geïnstalleerde Postman. Gebruik de volgende stappen om Postman-verificatie in te stellen met uw Brightspace-app:
- Start Postbode.
- U zou moeten worden gevraagd met een Slag venster. Onder de standaard Nieuwe makenselecteren Collectie.
- Geef een Naam voor je nieuwe collectie (bijv. "Brightspace API Testing").
- Selecteer het pictogram Machtiging tabblad.
- Van de Type dropdown, selecteer OAuth 2.0.
- Voor de Verificatiegegevens toevoegen aan dropdown, selecteer Headers aanvragen.
- Klikken Nieuw toegangstoken ophalen.
- De Nieuw toegangstoken ophalen venster wordt geopend. U moet elk veld als volgt configureren:
- Zorg voor een Naam van token waarde (bijv. "Brightspace Dev Environment Token").
- Subsidietype ingesteld op Autorisatie Code.
- Stel de terugbel-URL in op:
https://oauth.pstmn.io/v1/browser-callback
(volgens Postman OAuth 2.0 documentatie) - Stel de verificatie-URL in op: https://auth.brightspace.com/oauth2/auth
- Stel de URL van het toegangstoken in op: https://auth.brightspace.com/core/connect/token
- Klant-ID moet overeenkomen met de waarde van de client-id van uw Brightspace-app.
- Geheim van de klant moet overeenkomen met de waarde Client Secret van uw Brightspace-app.
- Draagwijdte moet overeenkomen met de waarde Bereik van uw Brightspace-app.
- Staat kan elke waarde zijn. Deze waarde is een beveiligingsfunctie die bedoeld is om te beschermen tegen vervalsing van Cross Site-verzoeken. Voor testdoeleinden is deze waarde niet erg belangrijk; Maar voor productie-apps moet je ervoor zorgen dat je een cryptografisch veilige waarde gebruikt.
- Klant Machtiging ingesteld op Verzenden als Basic Auth-header.
- Klikken Token aanvragen. U wordt gevraagd een aanmeldingsvenster te openen voor uw exemplaar van Brightspace. Voer de Gebruikersnaam en Wachtwoord van de gebruiker waarmee u API-verzoeken wilt uitvoeren en klik op Aanmelden. Als dit lukt, ziet u een toestemmingsprompt om het gebruik van de toepassing te bevestigen. Accepteer deze prompt (houd er rekening mee dat deze prompt alleen optreedt voor een gebruiker wanneer deze de app voor het eerst opent).
- Het venster zou moeten sluiten en u ziet een Toegang Token waarde die in de collectie is ingevoerd. Scrol naar de onderkant van het venster en klik op Token gebruiken.
- Klikken Scheppen om je collectie te maken.
Je hebt nu een Postman Collection verbonden met Brightspace met behulp van OAuth 2.0. De volgende stap is het toevoegen van een API-verzoek aan uw collectie.
Brightspace-verzoeken toevoegen aan uw Postman-collectie
Een van de krachtige aspecten van Postman is dat je één of meerdere API-verzoeken aan een collectie kunt toevoegen.
Een verzoek toevoegen aan je collectie
- Klikken Nieuw.
- Selecteer een Verzoek en voer een Naam van het verzoek en Beschrijving van het verzoek.
- Zorg ervoor dat uw collectie in orde is Uitverkoren als de opslaglocatie. Klikken Opslaan in {uw verzameling}.
Op dit punt wordt u teruggebracht naar de bestemmingspagina van Postman, maar nu heeft u de mogelijkheid om een specifiek API-verzoek toe te voegen. U kunt Postman de details verstrekken van elke Brightspace API-route die u in dit stadium wilt testen. Je kunt een verzoek toevoegen om een lijst te KRIJGEN van alle quizzen die in een specifieke cursus bestaan.
- Geef voor het eerste veld op TOEVOEGEN als de HTTP-methode.
- In het veld URL aanvragen moet u het volledige API-eindpunt bouwen. Dit geldt ook voor de URL van het exemplaar.
- Begin met de URL van uw instantie.
- Voer de URL in van de API die u wilt aanroepen (bijv. /d2l/api/le/(version)/(orgUnitId)/quizzes/ ).
- Vervang de (versie)waarde door uw huidige API-versie.
- Vervang uw orgUnitId door de cursus die u wilt targeten.
- Klik op de knop Machtiging Tab en zorgen ervoor Verificatie erven van ouder voor Type is ingesteld.
- Met de ingevoerde aanvraaggegevens en de specifieke autorisatie, klikt u op Verzenden om de nieuwe aanvraag te testen.
- U zou nu een antwoord van 200 moeten ontvangen met een reeks quizzen die momenteel beschikbaar zijn voor uw gebruiker om te zien in de specifieke orgUnit.
Als er geen quizzen bestaan, kun je een 404-fout verwachten voor geen gevonden quizzen. Als uw gebruiker geen rechten heeft om quizzen te zien, ontvangt u de foutmelding 403 niet geautoriseerd.
Geavanceerd gebruik van Postman
Postman bevat extra functies die zowel tijd besparen als het begrip van een API-route vergroten. Postbode maakt het mogelijk om Collectie en/of Milieu Variabelen. Hiermee kunt u waarden vervangen in uw aanvragen voor het snel toevoegen van nieuwe eindpunten of het testen in verschillende instanties. Hier zijn enkele ideeën om u op weg te helpen:
- Maak een omgevingsvariabele die de URL van uw Brightspace-exemplaar definieert
- Maak een versievariabele om de waarde op te slaan die in uw API-URL's is opgegeven
Een andere geweldige functie is Scripts. Postman bevat een runtime-omgeving (op basis van Node.js) waarmee u dynamische code aan uw aanvragen kunt toevoegen, hetzij pre-request of direct nadat een oproep is gedaan. Gebruikers kunnen scripts voor en na aanvraag toevoegen aan verzamelingenmappen of specifieke verzoeken. Scripts zijn geweldig voor situaties zoals:
- Polling naar de API-versie van een exemplaar en het leveren van de waarde aan een variabele voor een volgende aanvraag
- De waarde van een OrgUnitId opslaan en doorgeven voor een zoekopdracht in een volgende aanvraag
- Het uitvoeren van een berekeningsfunctie voordat de gegevens worden ingediend in een POST-API
Problemen met Postman en Brightspace
Onze evaluatie van Postman was veelbelovend en positief. We hebben echter een aantal problemen ondervonden waarvan u op de hoogte moet zijn.
Cookies wissen: Op het moment van publicatie van dit artikel hebben we gemerkt dat er geen problemen zijn de eerste keer dat OAuth-tokens worden gegenereerd. Latere pogingen hebben echter problemen. Om dit probleem op te lossen, raden we aan om Cookies wissen binnen Postbode.
Geen inlogomleiding: Bij het genereren van een OAuth-token wordt de gebruiker van Postman naar de inlogpagina van de Brightspace-instantie gestuurd waartegen ze aan het ontwikkelen zijn. Er zijn geen opties om door te verwijzen naar een andere Brightspace-inlogpagina in de ingebouwde browser van Postman. Dit is alleen een probleem als het gebruikersaccount waarmee u aan het ontwikkelen bent, niet is geregistreerd bij de Identity Provider van uw hoofdinlogpagina.
We evalueren beide bovenstaande kwesties. We zijn echter van mening dat dit beide problemen zijn binnen Postman. We staan open voor suggesties over hoe we deze problemen beter kunnen omzeilen, en we zullen alle updates die we in dit artikel ontvangen, verstrekken.
Conclusie
Laat ons weten over uw ervaring met het gebruik van Postman en deel met ons alle Postman-collecties die u ontwikkelt. Als er een andere API-testclient is die u verkiest boven Postman, willen we dat graag weten zodat we deze ook kunnen testen.
Voor meer informatie over het gebruik van Postman, zie Leer Postbode met Paul.
Afbeelding: Bekijk de details van een aanvraag op het aanvraagscherm.
