Referenční dokumentace ke službě Azure Digital Twins Swagger

Důležité

Byla vydána nová verze služby Azure Digital Twins. Vzhledem k rozšířeným funkcím nové služby se původní služba Azure Digital Twins (popsaná v této sadě dokumentace) vyřadila z provozu.

Pokud chcete zobrazit dokumentaci k nové službě, navštivte aktivní dokumentaci ke službě Azure Digital Twins.

Každá zřízená instance Azure Digital Twins zahrnuje vlastní automaticky vygenerovanou referenční dokumentaci ke Swaggeru.

Swagger nebo OpenAPI spojuje složité informace rozhraní API do interaktivního referenčního prostředku nezávislého na jazyce. Swagger poskytuje zásadní referenční materiál o tom, které JSON datové části, HTTP metody a konkrétní koncové body použít k provádění operací s rozhraním API.

Souhrn Swaggeru

Swagger poskytuje interaktivní souhrn vašeho rozhraní API, který zahrnuje:

• Informace o rozhraní API a objektových modelech
• Koncové body rozhraní REST API, které určují požadované datové části požadavků, hlavičky, parametry, cesty kontextu a metody HTTP.
• Testování funkcí rozhraní API
• Ukázkové informace o odpovědi použité k ověření a potvrzení odpovědí HTTP
• Informace o kódu chyby

Swagger je pohodlný nástroj, který pomáhá s vývojem a testováním volání provedených v rozhraních API pro správu služby Azure Digital Twins.

Návod

K demonstraci sady funkcí rozhraní API je poskytován náhled Swaggeru. Hostuje se v docs.westcentralus.azuresmartspaces.net/management/swagger.

K vlastní vygenerované dokumentaci k rozhraní API pro správu Swaggeru můžete přistupovat na adrese:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Název	Nahradit za
NÁZEV_VAŠEHO_INSTANCE	Název instance služby Azure Digital Twins
VAŠE_MÍSTO	V jaké oblasti serveru je vaše instance hostovaná

Referenční materiál

Automaticky generovaný referenční materiál Swagger poskytuje rychlý přehled důležitých konceptů, dostupných koncových bodů rozhraní API pro správu a popis každého objektového modelu, který pomáhá s vývojem a testováním.

Stručný souhrn popisuje rozhraní API.

V seznamu jsou uvedeny také objektové modely rozhraní API pro správu.

Pro podrobnější souhrn klíčových atributů můžete vybrat každý uvedený objektový model.

Vygenerované objektové modely Swaggeru jsou vhodné ke čtení všech dostupných objektů a rozhraní API služby Azure Digital Twins . Vývojáři můžou tento prostředek použít při vytváření řešení ve službě Azure Digital Twins.

Souhrn koncového bodu

Swagger také poskytuje podrobný přehled všech koncových bodů, které tvoří rozhraní API pro správu.

Každý uvedený koncový bod obsahuje také požadované informace o požadavku, například:

• Požadované parametry.
• Požadované datové typy parametrů.
• Metoda HTTP pro přístup k prostředku

Výběrem jednotlivých prostředků zobrazíte jejich další obsah, abyste získali podrobnější přehled.

Testování koncových bodů pomocí Swaggeru

Jednou z výkonných funkcí Swaggeru je možnost otestovat koncový bod rozhraní API přímo prostřednictvím uživatelského rozhraní dokumentace.

Po výběru konkrétního koncového bodu se zobrazí tlačítko Vyzkoušet .

Rozbalte tento oddíl a zobrazte vstupní pole pro každý povinný a volitelný parametr. Zadejte správné hodnoty a vyberte Spustit.

Po provedení testu můžete ověřit data odpovědi.

Data odpovědi Swaggeru

Každý uvedený koncový bod obsahuje také základní data odpovědi pro ověření vývoje a testů. Mezi tyto příklady patří stavové kódy a JSON pro úspěšné požadavky HTTP.

Mezi příklady patří také kódy chyb, které vám pomůžou ladit nebo zlepšit neúspěšné testy.

Autorizace Swagger OAuth 2.0

Poznámka:

• Hlavní uživatel, který vytvořil prostředek Azure Digital Twins, bude mít přiřazenu roli Správce prostoru a bude moci vytvářet další přiřazení rolí pro ostatní uživatele. Tito uživatelé a jejich role mohou být oprávněni přistupovat k API.

1. Postupujte podle kroků v rychlém startu a vytvořte a nakonfigurujte aplikaci Azure Active Directory. Případně můžete znovu použít existující registraci aplikace.

2. Do registrace aplikace Azure Active Directory přidejte následující identifikátor URI přesměrování:

   

   https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
   

   Název	Nahradit za	Příklad
   YOUR_SWAGGER_URL	Adresa URL dokumentace k rozhraní REST API pro správu, která se nachází na portálu	https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

3. Zaškrtněte políčko Implicitní udělení>přístupových tokenů , abyste umožnili použití toku implicitního udělení OAuth 2.0. Vyberte Konfigurovat a pak Uložit.

4. Zkopírujte ID klienta vaší aplikace Azure Active Directory.

Po dokončení registrace azure Active Directory:

1. Na stránce swaggeru vyberte tlačítko Autorizovat .

   

2. Vložte ID aplikace do pole client_id .

   

3. Pak budete přesměrováni na následující modální okno úspěchu.

   **

Další informace o interaktivním testování požadavků chráněných OAuth 2.0 najdete v oficiální dokumentaci .

Další kroky

• Další informace o objektových modelech Služby Azure Digital Twins a grafu prostorové inteligence najdete v tématu Vysvětlení modelů objektů Služby Azure Digital Twins.

• Informace o ověřování pomocí rozhraní API pro správu najdete v tématu Ověřování pomocí rozhraní API.