Sdílet prostřednictvím

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

  • Článek

Důležité

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

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 Swaggeru.

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

Souhrn Swaggeru

Swagger poskytuje interaktivní souhrn 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, kontextové cesty 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.

Tip

K předvedení sady funkcí rozhraní API se poskytuje Swagger sneak Preview. Hostuje se v docs.westcentralus.azuresmartspaces.net/management/swagger.

Můžete získat přístup k vlastní vygenerované dokumentaci k rozhraní API pro správu Swaggeru na adrese:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
Name Nahradit hodnotou
YOUR_INSTANCE_NAME Název instance služby Azure Digital Twins
YOUR_LOCATION Na které oblasti serveru je vaše instance hostovaná

Referenční materiál

Automaticky vygenerovaný 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ý vám pomůže s vývojem a testováním.

Stručný souhrn popisuje rozhraní API.

Souhrn A přehled rozhraní API Swaggeru

Jsou uvedeny také modely objektů rozhraní API pro správu.

Modely Swagger uvedené v dolní části uživatelského rozhraní Swagger

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

Modely Swagger se rozšířily a přečetly si obsah 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 žádosti, například:

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

Koncové body Swaggeru zobrazené v uživatelském rozhraní Swaggeru

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 .

Swagger Try it out button

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

Příklad výsledku swaggerem

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 k ověření vývoje a testů. Mezi tyto příklady patří stavové kódy a JSON pro úspěšné požadavky HTTP.

Příklad odpovědi JSON Swaggeru

Příklady zahrnují také kódy chyb, které pomáhají ladit nebo zlepšit neúspěšné testy.

Autorizace Swagger OAuth 2.0

Poznámka

  • Objekt zabezpečení uživatele, který vytvořil prostředek Azure Digital Twins, bude mít přiřazení role Správce prostoru a bude moct vytvořit další přiřazení rolí pro ostatní uživatele. Tito uživatelé a jejich role můžou být oprávněni volat rozhraní API.

  1. Pomocí kroků v rychlém startu 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í :

    Registrace adresy URL přesměrování Swaggeru v AAD 

    https://YOUR_SWAGGER_URL/ui/oauth2-redirect-html
    Name Nahradit hodnotou 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škrtnutím políčka Implicitní udělení>přístupových tokenů povolte použití implicitního toku udělení OAuth 2.0. Vyberte Konfigurovat a pak uložit.

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

Po dokončení registrace Azure Active Directory:

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

    Výběr tlačítka autorizace Swaggeru

  2. Vložte ID aplikace do pole client_id .

    Pole client_id Swaggeru

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

    Modální modální přesměrování Swaggeru

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

Další kroky