Megosztás a következőn keresztül:

Kérések küldése az Azure Digital Twins API-knak a Postman használatával

  • Cikk

A Postman egy REST-tesztelési eszköz, amely alapvető HTTP-kérési funkciókat biztosít egy asztali és beépülő modulalapú grafikus felhasználói felületen. Használatával HTTP-kéréseket készíthet, és elküldheti őket az Azure Digital Twins REST API-knak. Ez a cikk bemutatja, hogyan konfigurálhatja a Postman REST-ügyfelet az Azure Digital Twins API-k használatához. Ezek az információk az Azure Digital Twins szolgáltatásra vonatkoznak.

Ez a cikk a következő lépésekről tartalmaz információkat:

  1. Az Azure CLI használatával lekérhet egy tulajdonosi jogkivonatot , amellyel API-kéréseket végezhet a Postmanben.
  2. Állítson be egy Postman-gyűjteményt, és konfigurálja a Postman REST-ügyfelet a tulajdonosi jogkivonat hitelesítésére. A gyűjtemény beállításakor az alábbi lehetőségek közül választhat:
    1. Importálja az Azure Digital Twins API-kérések előre összeállított gyűjteményét.
    2. Hozzon létre saját gyűjteményt az alapoktól.
  3. Adjon hozzá kéréseket a konfigurált gyűjteményhez , és küldje el őket az Azure Digital Twins API-knak.

Az Azure Digital Twins két api-készlettel rendelkezik, amelyekkel dolgozhat: adatsíkkal és vezérlősíkkal. Az API-készletek közötti különbségről további információt az Azure Digital Twins API-k és az SDK-k című témakörben talál. Ez a cikk mindkét API-csoport adatait tartalmazza.

Előfeltételek

Ha a Postman használatával szeretné elérni az Azure Digital Twins API-kat, be kell állítania egy Azure Digital Twins-példányt, és le kell töltenie a Postmant. A szakasz többi része végigvezeti ezen lépéseken.

Az Azure Digital Twins-példány beállítása

Az Azure Digital Twins ebben a cikkben való használatához szüksége lesz egy Azure Digital Twins-példányra és a használatához szükséges engedélyekre. Ha már beállított egy Azure Digital Twins-példányt, használhatja ezt a példányt, és ugorjon a következő szakaszra. Ellenkező esetben kövesse a példány és a hitelesítés beállítása című témakör utasításait. Az utasítások olyan információkat tartalmaznak, amelyek segítenek ellenőrizni, hogy sikeresen végrehajtotta-e az egyes lépéseket.

A példány beállítása után jegyezze fel a példány állomásnevét. A gazdagép nevét az Azure Portalon találja.

Postman letöltése

Ezután töltse le a Postman-ügyfél asztali verzióját.

Tulajdonosi jogkivonat lekérése

Most, hogy beállította a Postmant és az Azure Digital Twins-példányt, le kell szereznie egy tulajdonosi jogkivonatot, amelyet a Postman kér az Azure Digital Twins API-k általi engedélyezéshez.

Ezt a jogkivonatot többféleképpen is beszerezheti. Ez a cikk az Azure CLI használatával jelentkezik be az Azure-fiókjába, és jogkivonatot szerez be.

Ha helyileg telepítette az Azure CLI-t, a következő parancsok futtatásához parancssort indíthat el a számítógépen. Ellenkező esetben megnyithat egy Azure Cloud Shell-ablakot a böngészőben, és ott futtathatja a parancsokat.

  1. Először győződjön meg arról, hogy a megfelelő hitelesítő adatokkal van bejelentkezve az Azure-ba a következő parancs futtatásával:

    az login

  2. Ezután az az account get-access-token paranccsal szerezze be a tulajdonosi jogkivonatot az Azure Digital Twins szolgáltatáshoz való hozzáféréssel. Ebben a parancsban meg kell adnia az Azure Digital Twins szolgáltatásvégpont erőforrás-azonosítóját, hogy lekérjen egy hozzáférési jogkivonatot, amely hozzáfér az Azure Digital Twins-erőforrásokhoz.

    A jogkivonat szükséges környezete attól függ, hogy milyen API-kat használ, ezért az alábbi fülek segítségével válasszon az adatsík és a vezérlősík API-k között.

    Az adatsík API-ival használható jogkivonat lekéréséhez használja a következő statikus értéket a jogkivonat-környezethez: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Ez az érték az Azure Digital Twins szolgáltatásvégpont erőforrás-azonosítója.

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

    Megjegyzés:

    Ha az Azure Digital Twins-példányt egy olyan szolgáltatásnévvel vagy felhasználói fiókkal kell elérnie, amely egy másik Microsoft Entra-bérlőhöz tartozik a példánytól, jogkivonatot kell kérnie az Azure Digital Twins-példány "otthoni" bérlőjétől. A folyamatról további információt az alkalmazáshitelesítési kód írása című témakörben talál.

  3. Másolja ki az eredmény értékét accessToken , és mentse a következő szakaszban való használatra. Ez az érték a jogkivonat értéke , amelyet a Postmannek kell megadnia a kérések engedélyezéséhez.

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

Tipp.

Ez a jogkivonat legalább öt percig és legfeljebb 60 percig érvényes. Ha elfogy az aktuális jogkivonatra vonatkozó idő, megismételheti az ebben a szakaszban ismertetett lépéseket egy új jogkivonat beszerzéséhez.

Ezután beállítja a Postmant, hogy ezzel a jogkivonattal API-kéréseket küldjön az Azure Digital Twinsnek.

Tudnivalók a Postman-gyűjteményekről

A Postman-kérelmek gyűjteményekbe (kéréscsoportokba) vannak mentve. Amikor gyűjteményt hoz létre a kérések csoportosításához, egyszerre számos kérésre alkalmazhat általános beállításokat. A gyakori beállítások jelentősen leegyszerűsíthetik az engedélyezést, ha több kérést szeretne létrehozni az Azure Digital Twins API-khoz, mivel ezeket a részleteket csak egyszer kell konfigurálnia a teljes gyűjteményhez.

Az Azure Digital Twins használatakor első lépésként importálhatja az összes Azure Digital Twins-kérés előre összeállított gyűjteményét. Érdemes importálni ezt a gyűjteményt, ha az API-kat vizsgálja, és szeretne gyorsan beállítani egy projektet kérési példákkal.

Azt is megteheti, hogy az alapoktól indul, ha létrehoz egy saját üres gyűjteményt, és feltölti azokat olyan egyedi kérésekkel, amelyek csak a szükséges API-kat hívják meg.

A következő szakaszok mindkét folyamatot ismertetik. A cikk további része a helyi Postman-alkalmazásban történik, ezért most nyissa meg a Postman alkalmazást a számítógépén.

Azure Digital Twins API-k importálása

Az Azure Digital Twins postmanbeli használatának első lépéseinek gyors módja az API-kra vonatkozó kérések előre összeállított gyűjteményének importálása. Az alábbi lépéseket követve importálhat egy népszerű Azure Digital Twins-adatsík API-kérések gyűjteményét, amelyek mintakérési adatokat tartalmaznak.

  1. A Postman főablakában válassza az Importálás gombot. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. Az alábbi Importálás ablakban válassza a Hivatkozás lehetőséget, és adja meg a következő URL-címet: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Ezután válassza az Importálás lehetőséget a megerősítéshez.

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

Az újonnan importált gyűjtemény mostantól látható a fő Postman-nézetben, a Gyűjtemények lapon.

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

Tipp.

Az Azure Digital Twins API-k egy bizonyos verziójához (beleértve a vezérlősíkot vagy az adatsíkot is) tartozó API-hívások teljes készletének importálásához gyűjteményekként is importálhatja a Swagger-fájlokat. A vezérlősík és az adatsík API-k Swagger-fájljaira mutató hivatkozásokért lásd: Azure Digital Twins API-k és SDK-k.

Ezután lépjen tovább a következő szakaszra, és adjon hozzá egy tulajdonosi jogkivonatot a gyűjteményhez engedélyezés céljából, és csatlakoztassa az Azure Digital twins-példányhoz.

Engedélyezés konfigurálása

Ezután szerkessze a létrehozott gyűjteményt, hogy konfiguráljon néhány hozzáférési részletet. Jelölje ki a létrehozott gyűjteményt, és válassza a További műveletek megtekintése ikont a műveletbeállítások megjelenítéséhez. Select Edit.

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

Az alábbi lépéseket követve adjon hozzá egy tulajdonosi jogkivonatot a gyűjteményhez engedélyezés céljából. Használja a tulajdonosi jogkivonat lekérése szakaszban összegyűjtött tokenértéket, hogy a gyűjtemény összes API-kéréséhez használhassa.

  1. A gyűjtemény szerkesztési párbeszédpanelén győződjön meg arról, hogy az Engedélyezés lapon van.

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

  2. Állítsa be a típust OAuth 2.0-ra, és illessze be a hozzáférési jogkivonatot a Hozzáférési jogkivonat mezőbe. A használt API típusához a megfelelő jogkivonatot kell használnia, mivel az adatsík API-k és a vezérlősík API-k különböző jogkivonatai vannak. Válassza a Mentés parancsot.

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

    Tipp.

    Bekapcsolhatja a jogkivonat-megosztást, ha a jogkivonatot a Postman-felhőben szeretné tárolni, és esetleg megoszthatja a jogkivonatát másokkal.

Egyéb konfiguráció

A gyűjteményhez megadott változók beállításával segíthet a gyűjteménynek az Azure Digital Twins-erőforrásokhoz való egyszerű kapcsolódásában. Ha egy gyűjtemény számos kérése ugyanazt az értéket igényli (például az Azure Digital Twins-példány gazdagépnevét), az értéket egy változóban tárolhatja, amely a gyűjtemény minden kérésére vonatkozik. Az Azure Digital Twins-gyűjtemény előre létrehozott változókkal rendelkezik, amelyeket a gyűjtemény szintjén állíthat be.

  1. A gyűjtemény szerkesztési párbeszédpaneljén lépjen a Változók lapra.

  2. A gyűjtemény változóinak értékeit az alábbi táblázat segítségével állíthatja be:

    Változó API-készlet Leírás
    digitaltwins-hostname Data plane Az Azure Digital Twins-példány állomásneve. Ezt az értéket a példány áttekintési oldalán találja a Portálon.
    subscriptionId Control plane Az Azure-előfizetés azonosítója.
    digitalTwinInstance Control plane Az Azure Digital Twins-példány neve.

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

  3. Ha a gyűjtemény további változókkal rendelkezik, töltse ki és mentse ezeket az értékeket is.

  4. Válassza a Mentés parancsot.

Ha végzett a fenti lépésekkel, befejezte a gyűjtemény konfigurálását. Ha szeretné, bezárhatja a gyűjtemény szerkesztési lapját.

A kérések megismerése

Ezután ismerkedjen meg az Azure Digital Twins API-gyűjteményben található kérésekkel. Kibonthatja a gyűjteményt az előre létrehozott kérések megtekintéséhez (műveletkategóriák szerint rendezve).

A különböző kérések eltérő információkat igényelnek a példányról és az adatairól. Egy adott kérés létrehozásához szükséges összes információ megtekintéséhez keresse meg a kérés részleteit az Azure Digital Twins REST API referenciadokumentációjában.

A Postman-gyűjteményben lévő kérések részleteit az alábbi lépésekkel szerkesztheti:

  1. Válassza ki a listából a szerkeszthető részletek lekéréséhez.

  2. A mintagyűjtemény legtöbb kérése előre konfigurálva van úgy, hogy további módosítások nélkül fusson.

  3. Az alábbi képernyőképen a DigitalTwinModels Add API látható. A Törzs lapon láthatja a hozzáadni kívánt új modellt meghatározó JSON hasznos adatokat:

  4. Adja meg az Elérési út változók területén a Params lapon felsorolt változók értékeit.

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

  5. A kérés futtatásához használja a Küldés gombot.

Saját kéréseket is hozzáadhat a gyűjteményhez az Egyéni kérés hozzáadása szakaszban leírt eljárással.

Saját gyűjtemény létrehozása

Az Azure Digital Twins API-k meglévő gyűjteményének importálása helyett saját gyűjteményt is létrehozhat az alapoktól. Ezt követően az Azure Digital Twins REST API referenciadokumentációjával feltöltheti azokat egyedi kérésekkel.

Postman-gyűjtemény létrehozása

  1. Gyűjtemény létrehozásához válassza az Új gombot a Postman főablakában.

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

    Válasszon gyűjteménytípust.

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

  2. Megnyílik egy lap. Adja meg az új gyűjtemény részleteit. Válassza a Gyűjtemény alapértelmezett neve (Új gyűjtemény) melletti Szerkesztés ikont a saját választott névre való lecseréléséhez.

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

Ezután folytassa a következő szakaszsal, és adjon hozzá egy tulajdonosi jogkivonatot a gyűjteményhez engedélyezés céljából.

Engedélyezés konfigurálása

Az alábbi lépéseket követve adjon hozzá egy tulajdonosi jogkivonatot a gyűjteményhez engedélyezés céljából. Használja a tulajdonosi jogkivonat lekérése szakaszban összegyűjtött tokenértéket, hogy a gyűjtemény összes API-kéréséhez használhassa.

  1. Az új gyűjtemény szerkesztési párbeszédpaneljén lépjen az Engedélyezés lapra.

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

  2. Állítsa a típust OAuth 2.0-ra, illessze be a hozzáférési jogkivonatot a Hozzáférési jogkivonat mezőbe, és válassza a Mentés lehetőséget.

    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.

Ha végzett a fenti lépésekkel, befejezte a gyűjtemény konfigurálását. Ha szeretné, bezárhatja az új gyűjtemény szerkesztési lapját.

Az új gyűjtemény a Fő Postman nézetben, a Gyűjtemények lapon tekinthető meg.

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

Egyéni kérés hozzáadása

A gyűjtemény beállítása után hozzáadhatja saját kéréseit az Azure Digital Twin API-khoz.

  1. Kérés létrehozásához használja ismét az Új gombot.

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

    Válasszon egy kéréstípust.

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

  2. Ez a művelet megnyitja a SAVE REQUEST ablakot, ahol megadhatja a kérés nevét, megadhat egy opcionális leírást, és kiválaszthatja azt a gyűjteményt, amelynek része. Töltse ki a részleteket, és mentse a kérést a korábban létrehozott gyűjteménybe.

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

Most már megtekintheti a kérést a gyűjtemény alatt, és kiválaszthatja a szerkeszthető részletek lekéréséhez.

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

Kérés részleteinek megadása

Ha Postman-kérést szeretne küldeni az Egyik Azure Digital Twins API-nak, szüksége lesz az API URL-címére, valamint a szükséges részletekre. Ezeket az információkat az Azure Digital Twins REST API referenciadokumentációjában találja.

Egy példa lekérdezés folytatásához ez a cikk az Azure Digital Twins Query API használatával kérdezi le a példány összes digitális ikerpéldányát.

  1. Kérje le a kérelem URL-címét és írja be a referenciadokumentációból. A Query API esetében ez jelenleg POSThttps://digitaltwins-host-name/query?api-version=2020-10-31.

  2. A Postmanben adja meg a kérés típusát, és adja meg a kérelem URL-címét, és szükség szerint töltse ki a helyőrzőket az URL-címben. Használja a példány gazdagépnevét az Előfeltételek szakaszból.

    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. Ellenőrizze, hogy a Kérelem paramok lapján látható paraméterek megfelelnek-e a referenciadokumentációban leírtaknak. A Postmanben lévő kéréshez a api-version paraméter automatikusan ki lett töltve, amikor a kérelem URL-címét az előző lépésben adták meg. A Query API-hoz ez az egyetlen szükséges paraméter, ezért ez a lépés kész.

  4. Az Engedélyezés lapon állítsa be a típust öröklő hitelesítési értéket a szülőtől. Ez azt jelzi, hogy ez a kérés a korábban beállított engedélyt fogja használni a teljes gyűjteményhez.

  5. Ellenőrizze, hogy a kérés fejlécei megegyeznek-e a referenciadokumentációban leírt fejlécekkel . Ebben a kérésben több fejléc is automatikusan ki lett töltve. A Query API-hoz nincs szükség fejlécbeállításokra, ezért ez a lépés kész.

  6. Ellenőrizze, hogy a kérelem törzse a Törzs lapon megfelel-e a referenciadokumentációban leírt igényeknek. A Query API-hoz JSON-törzsre van szükség a lekérdezés szövegének megadásához. Íme egy példatörzs ehhez a kéréshez, amely a példány összes digitális ikerpéldányát lekérdezi:

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

    Az Azure Digital Twins-lekérdezések készítéséről további információt az ikergráf lekérdezése című témakörben talál.

  7. Tekintse meg a referenciadokumentációban azokat a mezőket, amelyekre szükség lehet a kérés típusához. A Query API esetében az összes követelmény teljesült a Postman-kérelemben, így ez a lépés befejeződött.

  8. A Küldés gombra kattintva elküldheti a befejezett kérést. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

A kérés elküldése után a válasz részletei megjelennek a Kérés alatti Postman ablakban. Megtekintheti a válasz állapotkódját és a szövegtörzset.

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

Összehasonlíthatja a választ a referenciadokumentációban megadott várt válaszadatokkal is, hogy ellenőrizze az eredményt, vagy többet tudjon meg a felmerülő hibákról.

Következő lépések

A Digital Twins API-kkal kapcsolatos további információkért olvassa el az Azure Digital Twins API-kat és az SDK-kat, vagy tekintse meg a REST API-k referenciadokumentációját.