Použití nástroje Postman k odesílání požadavků rozhraním AZURE DIGITAL TWINS API

Postman je testovací nástroj REST, který poskytuje klíčové funkce požadavků HTTP v grafickém uživatelském rozhraní založeném na desktopu a modulu plug-in. Můžete ho použít k tvorbě požadavků HTTP a jejich odeslání do rozhraní AZURE DIGITAL TWINS ROZHRANÍ REST API.

Tento článek popisuje, jak nakonfigurovat klienta REST Postman pro interakci s Azure Digital Twins API pomocí následujících kroků:

1. Pomocí Azure CLI získejte bearer token, který budete používat k žádostem rozhraní API v nástroji Postman.
2. Nastavte kolekci Postman a nakonfigurujte klienta REST Postman tak, aby k ověření používá váš bearer token. Při nastavování kolekce můžete zvolit jednu z těchto možností:
   1. Import předem sestavené kolekce požadavků Azure Digital Twins API.
   2. Vytvořte si vlastní kolekci od začátku.
3. Přidejte požadavky do nakonfigurované kolekce a odešlete je do Azure Digital Twins API.

Azure Digital Twins dvě sady rozhraní API, se kterou můžete pracovat: rovina dat a řídicí rovina. Další informace o rozdílech mezi těmito sadami rozhraní API najdete v Azure Digital Twins API a sadách SDK. Tento článek obsahuje informace o obou sadách rozhraní API.

Požadavky

Pokud chcete pokračovat v přístupu k rozhraním API Azure Digital Twins Postman, musíte nastavit instanci Azure Digital Twins a stáhnout postman. Zbytek této části vás provede těmito kroky.

Nastavení Azure Digital Twins instance

Pokud chcete s Azure Digital Twins v tomto článku pracovat, musíte nejprve nastavit instanci Azure Digital Twins . Potřebujete také požadovaná oprávnění k jeho použití. Pokud už máte instanci Azure Digital Twins, můžete ji použít.

Jinak postupujte podle pokynů v tématu Nastavení instance a ověřování. Pokyny obsahují informace, které vám pomůžou ověřit, že jste jednotlivé kroky úspěšně dokončili.

Po nastavení instance si poznamenejte následující hodnoty. Tyto hodnoty budete potřebovat pro připojení k instanci později:

• Název hostitele instance. Název hostitele najdete v části Azure Portal.
• Předplatné Azure, které jste použili k vytvoření instance. Bude fungovat jeho název nebo ID. Předplatné najdete na stránce Přehled vaší instance v Azure Portal .

Stáhnout Postman

Pak stáhněte desktopovou verzi klienta Postman.

Získání bearerového tokenu

Teď, když jste nastavili Nástroj Postman a instanci Azure Digital Twins, budete muset získat nosný token, který může požadavek Postman použít k autorizaci pro rozhraní API Azure Digital Twins api.

Tento token můžete získat několika způsoby. Tento článek používá Azure CLI k přihlášení k účtu Azure a získání tokenu tímto způsobem.

Pokud máte azure CLI nainstalované místně,můžete na svém počítači spustit příkazový řádek a spustit následující příkazy. Jinak můžete otevřít okno Azure Cloud Shell prohlížeči a spustit příkazy tam.

1. Nejprve spuštěním následujícího příkazu ověřte, že jste k Azure přihlášeni pomocí příslušných přihlašovacích údajů:

   az login
   

2. Dále pomocí příkazu az account get-access-token získejte bearer token s přístupem k Azure Digital Twins službě. V tomto příkazu předáte ID prostředku koncového bodu služby Azure Digital Twins, abyste získali přístupový token, který má přístup k Azure Digital Twins prostředkům.

   Požadovaný kontext tokenu závisí na tom, kterou sadu rozhraní API používáte, takže si na následujících kartách můžete vybrat mezi rozhraními API roviny dat a řídicí roviny.

   • Rovina dat
   • Řídicí rovina

   Pokud chcete získat token pro použití s rozhraními API roviny dat, použijte pro kontext tokenu následující statickou hodnotu: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 . Toto je ID prostředku pro koncový Azure Digital Twins služby.

   az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0
   

   Poznámka

   Pokud potřebujete přístup ke své instanci Azure Digital Twins pomocí objektu služby nebo uživatelského účtu, který patří do jiného tenanta Azure Active Directory než instance, budete si muset vyžádat token z "domovského" tenanta instance Azure Digital Twins. Další informace o tomto procesu najdete v tématu Psaní ověřovacího kódu aplikace.

3. Zkopírujte hodnotu accessToken ve výsledku a uložte ji pro použití v další části. Toto je hodnota vašeho tokenu, kterou poskytnete aplikaci Postman k autorizaci vašich požadavků.

   

V dalším kroku nastavíte nástroj Postman, aby pomocí tohoto tokenu odeslal požadavky rozhraní API na Azure Digital Twins.

O kolekcích Postman

Požadavky v nástroji Postman se ukládají do kolekcí (skupiny požadavků). Když vytváříte kolekci pro seskupování požadavků, můžete použít běžná nastavení pro mnoho požadavků najednou. To může výrazně zjednodušit autorizaci, pokud máte v plánu vytvořit více než jeden požadavek na rozhraní AZURE DIGITAL TWINS API, protože tyto podrobnosti musíte nakonfigurovat jenom jednou pro celou kolekci.

Při práci s Azure Digital Twins můžete začít importem předem sestavené kolekce všech požadavků na Azure Digital Twins dat. Můžete to udělat, pokud zkoumáte rozhraní API a chcete rychle nastavit projekt s příklady požadavků.

Alternativně se můžete rozhodnout začít od začátku vytvořením vlastní prázdné kolekce a naplněním jednotlivých požadavků, které volají pouze rozhraní API, která potřebujete.

Oba tyto procesy jsou popsány v následujících částech. Zbytek článku se bude odehrát v místní aplikaci Postman, takže teď otevřete aplikaci Postman na svém počítači.

Import kolekce Azure Digital Twins API

Rychlým způsobem, jak začít s Azure Digital Twins v Postmanu, je importovat předem vytvořenou kolekci požadavků pro rozhraní API Azure Digital Twins rozhraní API.

Stažení souboru kolekce

Prvním krokem při importu sady rozhraní API je stažení kolekce. Výběrem karty níže pro vaši volbu roviny dat nebo řídicí roviny zobrazíte předem sestavené možnosti shromažďování.

Tady je postup, jak vybranou kolekci stáhnout do počítače, abyste ji mohli importovat do postmanu.

1. Pomocí výše uvedených odkazů otevřete soubor kolekce v GitHub v prohlížeči.
2. Výběrem tlačítka Raw otevřete nezpracovaný text souboru.
3. Zkopírujte text z okna a vložte ho do nového souboru na vašem počítači.
4. Uložte soubor s příponou .json (název souboru může být jakýkoliv, pokud si ho budete pamatovat, abyste ho později našli).

Import kolekce

Dále naimportujte kolekci do postmanu.

1. V hlavním okně Postman vyberte tlačítko Importovat.

2. V následujícím okně Importovat vyberte Upload Soubory a přejděte do souboru kolekce na počítači, který jste vytvořili dříve. Vyberte Otevřít.

3. Potvrďte výběrem tlačítka Importovat.

   

Nově importovaná kolekce se teď zobrazí v hlavním zobrazení Postman na kartě Kolekce.

Dále pokračujte k další části a přidejte do kolekce bearer token pro autorizaci a připojte ho k vaší instanci Azure Digital Twins.

Konfigurace autorizace

Dále upravte kolekci, kterou jste vytvořili, a nakonfigurujte některé podrobnosti o přístupu. Zvýrazněte kolekci, kterou jste vytvořili, a výběrem ikony Zobrazit další akce natáhněte nabídku. Vyberte Upravit.

Podle těchto kroků přidejte do kolekce bearer token pro autorizaci. Tady použijete hodnotu tokenu, kterou jste shromáždili v části Získání bearer tokenu, abyste ji mohli použít pro všechny požadavky rozhraní API ve vaší kolekci.

1. V dialogovém okně pro úpravy kolekce se ujistěte, že jste na kartě Autorizace.

   

2. Nastavte typ na OAuth 2,0, vložte přístupový token do pole přístupový token a vyberte Save (Uložit).

   

Další konfigurace

Prozkoumat žádosti

Dále Prozkoumejte požadavky v kolekci rozhraní API digitálních vláken Azure. Kolekci můžete rozbalit a zobrazit tak předem vytvořené požadavky (seřazené podle kategorie operace).

Různé požadavky vyžadují různé informace o vaší instanci a jejich datech. Pokud chcete zobrazit všechny informace potřebné k vytvoření konkrétní žádosti, vyhledejte podrobnosti žádosti v části digitální vlákna Azure REST API referenční dokumentaci.

Podrobnosti žádosti v kolekci po můžete upravit pomocí těchto kroků:

1. Vyberte ho ze seznamu, abyste si vyčetli jeho upravitelné podrobnosti.

2. Vyplňte hodnoty pro proměnné uvedené na kartě params v části proměnné cesty.

   

3. Na příslušných kartách zadejte všechny potřebné podrobnosti záhlaví nebo textu .

Po zadání všech požadovaných podrobností můžete žádost spustit pomocí tlačítka Odeslat .

Do kolekce můžete také přidat vlastní požadavky pomocí procesu popsaného v části přidat jednotlivé žádosti .

Vytvoření vlastní kolekce

Místo importu stávající kolekce všech rozhraní API digitálních vláken Azure můžete také vytvořit vlastní kolekci od začátku. Pak je můžete naplnit jednotlivými požadavky pomocí REST API Referenční dokumentace Azure Digitalrequests.

Vytvoření kolekce Postman

1. Chcete-li vytvořit kolekci, vyberte tlačítko Nový v hlavním okně pro odeslání.

   

   Vyberte typ kolekce.

   

2. Tím se otevře karta pro vyplňování podrobností o nové kolekci. Vyberte ikonu pro úpravy vedle výchozího názvu kolekce (Nová kolekce), abyste ji nahradili vlastní volbou názvu.

   

Dále pokračujte k další části a přidejte do kolekce nosný token pro autorizaci.

Konfigurace autorizace

Pomocí těchto kroků přidejte do kolekce nosný token pro autorizaci. V tomto případě použijete hodnotu tokenu , kterou jste shromáždili v sekci získat nosný token , aby ji bylo možné použít pro všechny požadavky rozhraní API v kolekci.

1. Pořád v dialogu Upravit pro novou kolekci přejděte na kartu autorizace .

   

2. Nastavte typ na OAuth 2,0, vložte přístupový token do pole přístupový token a vyberte Save (Uložit).

   

Až budete s výše uvedeným postupem hotovi, dokončili jste konfiguraci kolekce. Pokud chcete, můžete pro novou kolekci zavřít kartu upravit.

Nová kolekce se dá zobrazit v hlavním zobrazení pro odeslání na kartě kolekce.

Přidat jednotlivý požadavek

Teď, když je vaše kolekce nastavená, můžete přidat vlastní žádosti do digitálních rozhraní API Azure.

1. Pokud chcete vytvořit žádost, znovu použijte nové tlačítko.

   

   Vyberte typ požadavku.

   

2. Tato akce otevře okno Uložit žádost, kde můžete zadat název žádosti, dát mu volitelný popis a vybrat kolekci, do které je součást. Vyplňte podrobnosti a uložte požadavek do kolekce, kterou jste vytvořili dříve.

   

Teď si můžete svůj požadavek zobrazit v kolekci a vybrat ho, abyste si vyžádali jeho upravitelné podrobnosti.

Nastavit podrobnosti žádosti

Pokud chcete poslat žádost o odeslání do jedné z rozhraní API digitálních vláken Azure, budete potřebovat adresu URL rozhraní API a informace o tom, jaké podrobnosti vyžaduje. Tyto informace najdete v referenční dokumentaci ke službě Azure Digital Revlákens REST API.

Chcete-li pokračovat s příkladem dotazu, bude tento článek používat rozhraní API pro dotazy (a jeho referenční dokumentaci) k dotazování na všechny digitální vlákna v instanci.

1. Získejte adresu URL a typ žádosti z referenční dokumentace. Pro rozhraní API pro dotazování je aktuálně post https://digitaltwins-host-name/query?api-version=2020-10-31 .

2. V poli PSČ nastavte typ pro požadavek a zadejte adresu URL požadavku, podle potřeby vyplňte zástupné symboly v adrese URL. Tady budete používat název hostitele vaší instance z oddílu požadavky.

   

3. Ověřte, že parametry zobrazené pro požadavek na kartě params se shodují s hodnotami popsanými v referenční dokumentaci. Pro tento požadavek v poli api-version byl parametr automaticky vyplněn při zadání adresy URL požadavku v předchozím kroku. V případě rozhraní API pro dotazy se jedná o jediný požadovaný parametr, proto je tento krok hotový.

4. Na kartě autorizace nastavte typ pro dědění ověřování z nadřazené položky. To znamená, že tato žádost bude používat autorizaci, kterou jste nastavili dříve pro celou kolekci.

5. Ověřte, že hlavičky zobrazené pro požadavek na kartě hlavičky odpovídají názvům popsaným v referenční dokumentaci. Pro tento požadavek byly automaticky vyplněny několik záhlaví. V případě rozhraní API pro dotazy není nutné provádět žádné možnosti záhlaví, proto je tento krok hotový.

6. Ověřte, že text zobrazený pro požadavek na kartě tělo odpovídá potřebám popsaným v referenční dokumentaci. Pro rozhraní API pro dotazy je k zadání textu dotazu potřeba tělo JSON. Tady je příklad těla této žádosti, který se dotazuje na všechny digitální vlákna v instanci:

   

   Další informace o tom, jak vytvářet dotazy digitálních vláken Azure, najdete v tématu dotazování na dvojitou graf.

7. Podívejte se na referenční dokumentaci pro všechna další pole, která se můžou vyžadovat pro váš typ požadavku. V případě rozhraní API pro dotazování jsou nyní všechny požadavky splněny v žádosti post, takže tento krok je dokončen.

8. K odeslání dokončené žádosti použijte tlačítko Odeslat .

Po odeslání žádosti se v okně po žádosti zobrazí podrobnosti o odpovědi. Můžete zobrazit stavový kód odpovědi a jakýkoliv hlavní text.

Můžete také porovnat odpověď na očekávaná data odpovědi, která jsou uvedena v referenční dokumentaci, a ověřit výsledek nebo se dozvědět více o chybách, ke kterým dojde.

Další kroky

Pokud chcete získat další informace o rozhraních API digitálních vláken, přečtěte si rozhraní API a sady SDK digitálních vláken Azure, nebo si prohlédněte referenční dokumentaci pro rozhraní REST API.