Odesílání požadavků do rozhraní API služby Azure Digital Twins pomocí nástroje Postman

  • Článek

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 stolním počítači a modulu plug-in. Můžete ho použít k vytvoření požadavků HTTP a jejich odeslání do rozhraní REST API služby Azure Digital Twins. Tento článek popisuje, jak nakonfigurovat klienta REST postman pro interakci s rozhraními API služby Azure Digital Twins. Tyto informace jsou specifické pro službu Azure Digital Twins.

Tento článek obsahuje informace o následujících krocích:

  1. Pomocí Azure CLI získáte nosný token , který použijete k vytváření požadavků rozhraní API v Postmanu.
  2. Nastavte kolekci Postman a nakonfigurujte klienta REST Postman tak, aby k ověření používal nosný token. Při nastavování kolekce můžete zvolit jednu z těchto možností:
    1. Importujte předem vytvořenou kolekci požadavků rozhraní API služby Azure Digital Twins.
    2. Vytvořte si vlastní kolekci úplně od začátku.
  3. Přidejte do nakonfigurované kolekce požadavky a odešlete je do rozhraní API služby Azure Digital Twins.

Azure Digital Twins má dvě sady rozhraní API, se kterými můžete pracovat: rovinou dat a řídicí rovinou. Další informace o rozdílu mezi těmito sadami rozhraní API najdete v tématu Rozhraní API služby Azure Digital Twins a sady SDK. Tento článek obsahuje informace o obou sadách rozhraní API.

Předpoklady

Pokud chcete pokračovat v používání nástroje Postman pro přístup k rozhraním API služby Azure Digital Twins, musíte nastavit instanci Služby Azure Digital Twins a stáhnout postman. Zbývající část této části vás provede těmito kroky.

Nastavení instance Azure Digital Twins

Pokud chcete pracovat se službou Azure Digital Twins v tomto článku, budete potřebovat instanci služby Azure Digital Twins a požadovaná oprávnění k jeho použití. Pokud už máte nastavenou instanci Služby Azure Digital Twins, můžete tuto instanci použít a přeskočit k další části. V opačném případě postupujte podle pokynů v části Nastavení instance a ověřování. Pokyny obsahují informace, které vám pomůžou ověřit, že jste každý krok úspěšně dokončili.

Po nastavení instance si poznamenejte název hostitele instance. Název hostitele najdete na webu Azure Portal.

Stáhnout Postman

Dále si stáhněte desktopovou verzi klienta Postman.

Získání nosný token

Teď, když jste nastavili Postman a instanci Služby Azure Digital Twins, budete muset získat nosný token, který můžou požadavky Postman použít k autorizaci vůči rozhraním API služby Azure Digital Twins.

Existuje několik možných způsobů, jak tento token získat. Tento článek používá Azure CLI k přihlášení k účtu Azure a získání tokenu.

Pokud máte rozhraní příkazového řádku Azure CLI nainstalované místně, můžete na svém počítači spustit příkazový řádek a spustit následující příkazy. V opačném případě můžete otevřít okno Azure Cloud Shellu v prohlížeči a spustit příkazy tam.

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

    az login

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

    Požadovaný kontext tokenu závisí na tom, jakou sadu rozhraní API používáte, a proto pomocí následujících karet vyberte rozhraní API roviny dat a řídicí roviny .

    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 Tato hodnota je ID prostředku pro koncový bod služby Azure Digital Twins.

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

    Poznámka:

    Pokud potřebujete získat přístup k instanci Azure Digital Twins pomocí instančního objektu nebo uživatelského účtu, který patří do jiného tenanta Microsoft Entra z instance, budete muset požádat o 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 výsledku a uložte ji, aby se použila v další části. Tato hodnota je hodnota tokenu, kterou poskytnete postmanovi k autorizaci vašich požadavků.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

Tip

Tento token je platný nejméně pět minut a maximálně 60 minut. Pokud vám vypršel časový limit přidělený pro aktuální token, můžete opakováním kroků v této části získat nový.

Dále nastavíte Postman, aby pomocí tohoto tokenu nastavil požadavky rozhraní API na Azure Digital Twins.

O kolekcích Postman

Požadavky v Nástroji Postman se ukládají do kolekcí (skupin požadavků). Když vytvoříte kolekci pro seskupení požadavků, můžete použít běžná nastavení pro mnoho požadavků najednou. Běžná nastavení můžou výrazně zjednodušit autorizaci, pokud plánujete vytvořit více než jeden požadavek na rozhraní API služby Azure Digital Twins, protože tyto podrobnosti stačí nakonfigurovat jenom jednou pro celou kolekci.

Při práci s Azure Digital Twins můžete začít importem předem vytvořené kolekce všech požadavků Azure Digital Twins. Tuto kolekci můžete chtít importovat, pokud zkoumáte rozhraní API a chcete rychle nastavit projekt s příklady požadavků.

Alternativně můžete také začít od nuly vytvořením vlastní prázdné kolekce a jejím naplněním jednotlivými požadavky, které volají pouze potřebná rozhraní API.

Oba tyto procesy jsou popsány v následujících částech. Zbytek článku se odehrává v místní aplikaci Postman, takže pokračujte a otevřete aplikaci Postman na vašem počítači.

Import kolekce rozhraní API služby Azure Digital Twins

Rychlý způsob, jak začít s Azure Digital Twins v Postmanu, je importovat předem sestavenou kolekci požadavků pro rozhraní API. Podle následujících kroků naimportujte kolekci oblíbených požadavků rozhraní API roviny dat Služby Azure Digital Twins obsahující ukázková data požadavků.

  1. V hlavním okně nástroje Postman vyberte tlačítko Importovat . Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. V následujícím okně importu vyberte Odkaz a zadejte následující adresu URL: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Potom akci potvrďte výběrem možnosti Importovat .

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

Nově importovanou kolekci teď můžete vidět z hlavního zobrazení Postman na kartě Kolekce.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Tip

Pokud chcete importovat kompletní sadu volání rozhraní API pro určitou verzi rozhraní API služby Azure Digital Twins (včetně řídicí roviny nebo roviny dat), můžete také importovat soubory Swagger jako kolekce. Odkazy na soubory Swagger pro rozhraní API řídicí roviny a roviny dat najdete v tématu Rozhraní API a sady SDK služby Azure Digital Twins.

Dále pokračujte k další části a přidejte do kolekce nosný token pro autorizaci a připojte ho k instanci služby 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 zobrazte možnosti akcí. Vyberte položku Upravit.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

Následujícím postupem přidáte nosný token do kolekce pro autorizaci. Použijte hodnotu tokenu, kterou jste shromáždili v části Získat nosný token , 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 .

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Nastavte typ na OAuth 2.0 a vložte přístupový token do pole Přístupový token. Pro typ rozhraní API, které používáte, musíte použít správný token, protože pro rozhraní API roviny dat a rozhraní API řídicí roviny existují různé tokeny. Zvolte Uložit.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Tip

    Sdílení tokenů můžete zapnout, pokud chcete token uložit s požadavkem v cloudu Postman a případně ho sdílet s ostatními.

Další konfigurace

Kolekci můžete pomoct snadno připojit k prostředkům služby Azure Digital Twins nastavením některých proměnných poskytovaných v kolekci. Pokud mnoho požadavků v kolekci vyžaduje stejnou hodnotu (jako je název hostitele instance služby Azure Digital Twins), můžete hodnotu uložit do proměnné, která se vztahuje na každý požadavek v kolekci. Kolekce Azure Digital Twins obsahuje předem vytvořené proměnné, které můžete nastavit na úrovni kolekce.

  1. V dialogovém okně pro úpravy kolekce přejděte na kartu Proměnné .

  2. K nastavení hodnot proměnných v kolekci použijte následující tabulku:

    Proměnná Sada rozhraní API Popis
    digitaltwins-hostname Rovina dat Název hostitele instance Azure Digital Twins. Tuto hodnotu najdete na stránce přehledu vaší instance na portálu.
    subscriptionId Řídicí rovina ID vašeho předplatného Azure
    digitalTwinInstance Řídicí rovina Název instance služby Azure Digital Twins.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. Pokud vaše kolekce obsahuje další proměnné, vyplňte a uložte i tyto hodnoty.

  4. Zvolte Uložit.

Až dokončíte výše uvedené kroky, dokončíte konfiguraci kolekce. Pokud chcete, můžete zavřít kartu pro úpravy kolekce.

Prozkoumání požadavků

Dále prozkoumejte požadavky v kolekci rozhraní API služby Azure Digital Twins. Kolekci můžete rozbalit a zobrazit předem vytvořené požadavky (seřazené podle kategorie operace).

Různé požadavky vyžadují různé informace o vaší instanci a jejích datech. Pokud chcete zobrazit všechny informace potřebné k vytvoření konkrétní žádosti, vyhledejte podrobnosti žádosti v referenční dokumentaci k rozhraní REST API služby Azure Digital Twins.

Podrobnosti požadavku v kolekci Postman můžete upravit pomocí následujícího postupu:

  1. Vyberte ho ze seznamu a stáhněte si jeho upravitelné podrobnosti.

  2. Většina požadavků v ukázkové kolekci je předem nakonfigurovaná tak, aby běžela bez nutnosti provádět další změny.

  3. Následující snímek obrazovky ukazuje rozhraní API pro přidání modelu DigitalTwinModels. Na kartě Tělo uvidíte datovou část JSON, která definuje nový model, který chcete přidat:

  4. Vyplňte hodnoty proměnných uvedených na kartě Parametry v části Proměnné cesty.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. Pokud chcete žádost spustit, použijte tlačítko 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 existující kolekce rozhraní API služby Azure Digital Twins můžete také vytvořit vlastní kolekci úplně od začátku. Pak ho můžete naplnit jednotlivými požadavky pomocí referenční dokumentace k rozhraní REST API služby Azure Digital Twins.

Vytvoření kolekce Postman

  1. Pokud chcete vytvořit kolekci, vyberte v hlavním okně Postman tlačítko Nový .

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Zvolte typ kolekce.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. Otevře se karta. Vyplňte podrobnosti o nové kolekci. Vyberte ikonu Upravit vedle výchozího názvu kolekce (Nová kolekce) a nahraďte ji vlastním názvem.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

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

Konfigurace autorizace

Následujícím postupem přidáte nosný token do kolekce pro autorizaci. Použijte hodnotu tokenu, kterou jste shromáždili v části Získat nosný token , abyste ji mohli použít pro všechny požadavky rozhraní API ve vaší kolekci.

  1. V dialogovém okně pro úpravy nové kolekce přejděte na kartu Autorizace .

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Nastavte typ na OAuth 2.0, vložte přístupový token do pole Přístupový token a vyberte Uložit.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

Až dokončíte výše uvedené kroky, dokončíte konfiguraci kolekce. Pokud chcete, můžete kartu pro úpravy nové kolekce zavřít.

Novou kolekci si můžete prohlédnout z hlavního zobrazení Postman na kartě Kolekce.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

Přidání jednotlivé žádosti

Teď, když je vaše kolekce nastavená, můžete do rozhraní API služby Azure Digital Twin přidat vlastní požadavky.

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

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Zvolte typ požadavku.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. Tato akce otevře okno ULOŽIT POŽADAVEK, kde můžete zadat název žádosti, zadat volitelný popis a zvolit kolekci, ve které je součástí. Vyplňte podrobnosti a uložte žádost do dříve vytvořené kolekce.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

Teď můžete žádost zobrazit v kolekci a vybrat ji, aby se zobrazily její upravitelné podrobnosti.

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

Nastavení podrobností žádosti

Pokud chcete vytvořit požadavek Postman na jedno z rozhraní API služby Azure Digital Twins, budete potřebovat adresu URL rozhraní API a informace o tom, jaké podrobnosti vyžaduje. Tyto informace najdete v referenční dokumentaci k rozhraní REST API služby Azure Digital Twins.

Pokud chcete pokračovat v ukázkovém dotazu, tento článek použije rozhraní API pro dotazy azure Digital Twins k dotazování na všechna digitální dvojčata v instanci.

  1. Získejte adresu URL požadavku a zadejte ji z referenční dokumentace. Pro rozhraní API pro dotazy je to aktuálně POSThttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. V Nástroji Postman nastavte typ požadavku a zadejte adresu URL požadavku a podle potřeby vyplňte zástupné symboly v adrese URL. V části Požadavky použijte název hostitele vaší instance.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. Zkontrolujte, jestli parametry zobrazené pro požadavek na kartě Parametry odpovídají parametrům popsaným v referenční dokumentaci. Pro tento požadavek v Nástroji Postman api-version se parametr automaticky vyplnil při zadání adresy URL požadavku v předchozím kroku. Pro rozhraní API pro dotazy je to jediný povinný parametr, takže tento krok se provádí.

  4. Na kartě Autorizace nastavte typ na dědění ověřování z nadřazeného objektu. To znamená, že tento požadavek použije autorizaci, kterou jste nastavili dříve pro celou kolekci.

  5. Zkontrolujte, jestli záhlaví zobrazená pro požadavek na kartě Záhlaví odpovídají hlavičkám popsaným v referenční dokumentaci. U tohoto požadavku se automaticky vyplnilo několik hlaviček. Pro rozhraní API pro dotazy se nevyžaduje žádná z možností hlavičky, takže se tento krok dokončí.

  6. Zkontrolujte, jestli text zobrazený pro požadavek na kartě Text odpovídá potřebám popsaným v referenční dokumentaci. Pro rozhraní API pro dotazy se k zadání textu dotazu vyžaduje text JSON. Tady je příklad textu pro tento požadavek, který se dotazuje na všechna digitální dvojčata v instanci:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    Další informace o vytváření dotazů Azure Digital Twins najdete v tématu Dotazování na graf dvojčete.

  7. Projděte si referenční dokumentaci pro všechna další pole, která můžou být pro váš typ požadavku povinná. U rozhraní API pro dotazy jsou teď všechny požadavky splněné v požadavku Postman, takže tento krok je hotový.

  8. Pomocí tlačítka Odeslat odešlete dokončenou žádost. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

Po odeslání požadavku se podrobnosti odpovědi zobrazí v okně Postman pod požadavkem. Můžete zobrazit stavový kód odpovědi a jakýkoli základní text.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

Můžete také porovnat odpověď s očekávanými daty odpovědí zadanými v referenční dokumentaci, ověřit výsledek nebo získat další informace o případných chybách.

Další kroky

Další informace o rozhraních API služby Digital Twins najdete v rozhraních API služby Azure Digital Twins a sadách SDK nebo si projděte referenční dokumentaci k rozhraním REST API.