Ismerkedés a Visual Studio Code Azure API Center bővítményével

Api-k létrehozásához, felderítéséhez, kipróbálásához és felhasználásához használja az Azure API Center bővítményt a Visual Studio Code fejlesztői környezetében:

• API-k létrehozása – Az API-központban való regisztrálással felderíthetővé teheti az ön által létrehozott API-kat mások számára. A shift-left API tervezési megfelelősége integrált linting támogatással a Visual Studio Code-ba kerül. Győződjön meg arról, hogy az új API-verziók nem szakítják meg az API-felhasználókat a változásészlelés megszakításával.

• API-k felfedezése – Tallózás az API-központban található API-k között, és megtekintheti azok részleteit és dokumentációját.

• Próbálja ki az API-kat – Használja a Swagger felhasználói felületét vagy a REST-ügyfelet az API-kérések és válaszok megismeréséhez.

• API-k használata – API SDK-ügyfelek létrehozása a kedvenc nyelvhez( például JavaScript, TypeScript, .NET, Python és Java) a Microsoft Graphhoz, a GitHubhoz és egyebekhez SDK-kat létrehozó Microsoft Kiota motor használatával.

Előfeltételek

• Egy vagy több API-központ az Azure-előfizetésben. Ha még nem hozott létre egyet, olvassa el az API-központ létrehozása című rövid útmutatót.

  Jelenleg hozzá kell rendelnie a közreműködői szerepkört vagy magasabb engedélyeket a bővítményhez tartozó API-központok eléréséhez.

• Visual Studio Code

• Azure API Center-bővítmény a Visual Studio Code-hoz

Az alábbi Visual Studio Code-bővítmények nem kötelezőek, és csak bizonyos forgatókönyvekhez szükségesek a megadott módon:

• REST-ügyfélbővítmény – HTTP-kérések küldése és a válaszok megtekintése közvetlenül a Visual Studio Code-ban
• Microsoft Kiota-bővítmény – API-ügyfelek létrehozása
• Spektrális bővítmény – a shift-left API tervezési megfelelőségi ellenőrzéseinek futtatása a Visual Studio Code-ban
• Optic CLI – az API specifikációs dokumentumai közötti kompatibilitástörő változások észlelése
• GitHub Copilot – OpenAPI specifikációs fájlok létrehozása API-kódból

Beállítás

1. Telepítse a Visual Studio Code Azure API Center bővítményét a Visual Studio Code Marketplace-ről. Igény szerint telepítse az opcionális bővítményeket.
2. A Visual Studio Code bal oldali tevékenységsávján válassza az API-központot.
3. Ha nincs bejelentkezve az Azure-fiókjába, válassza a Bejelentkezés az Azure-ba... lehetőséget, és kövesse az utasításokat a bejelentkezéshez. Válasszon ki egy Azure-fiókot azzal az API-központtal (vagy API-központtal), amelyből meg szeretné tekinteni az API-kat. Adott előfizetésekre is szűrhet, ha sok megtekintési lehetőség közül választhat.

API-k regisztrálása

Regisztráljon egy API-t az API-központban közvetlenül a Visual Studio Code-ból, akár egyszeri műveletként, akár CI/CD-folyamatként regisztrálva.

1. A Parancskatalógus megnyitásához használja a Ctrl+Shift+P billentyűparancsot. Írja be az Azure API Centert : Regisztrálja az API-t , és nyomja le az Enter billentyűt.
2. Válassza ki, hogyan szeretné regisztrálni az API-t az API-központban:
   • Az API-k egyszeri regisztrációjához lépésről lépésre a legjobb.
   • A CI/CD egy előre konfigurált GitHub- vagy Azure DevOps-folyamatot ad hozzá az aktív Visual Studio Code-munkaterülethez, amely egy CI/CD-munkafolyamat részeként fut minden egyes forráskövetési véglegesítésen. Javasoljuk, hogy az API-központtal ci/CD használatával leltározza az API-kat, hogy az API metaadatai , beleértve a specifikációt és a verziót is, naprakészek maradjanak az API-központban, mivel az API folyamatosan fejlődik az idő múlásával.
3. Regisztrációs lépések végrehajtása:
   • Lépésről lépésre válassza ki az API-központot, amellyel API-kat regisztrálhat, és az API-regisztráció befejezéséhez választ kaphat az API-címek címével, típusával, életciklus-szakaszával, verziójával és specifikációjával.
   • CI/CD esetén válassza a GitHubot vagy az Azure DevOpsot az előnyben részesített forrásvezérlési mechanizmustól függően. Egy Visual Studio Code-munkaterületnek nyitva kell lennie ahhoz, hogy az Azure API Center-bővítmény hozzáadjon egy folyamatot a munkaterülethez. A fájl hozzáadása után végezze el a CI/CD-folyamatfájlban dokumentált lépéseket az Azure Pipeline/GitHub Action környezeti változóinak és identitásának konfigurálásához. A forráskövetésbe való leküldés során az API regisztrálva lesz az API-központban.

API-kialakítási megfelelőség

Annak érdekében, hogy az API-k létrehozása során a tervezési megfelelőség megfeleljen a szervezeti szabványoknak, a Visual Studio Code-hoz készült Azure API Center bővítmény integrált támogatást nyújt az API specifikációinak a Spectralnal való lintinghez.

1. A Parancskatalógus megnyitásához használja a Ctrl+Shift+P billentyűparancsot. Írja be az Azure API Centert : Állítsa be az aktív API stíluskalauzt , és nyomja le az Enter billentyűt.
2. Válassza ki a megadott alapértelmezett szabályok egyikét, vagy ha a szervezet már rendelkezik stíluskalauzsal, használja a Helyi fájl kiválasztása vagy a Távoli bemenet URL-cím kiválasztása lehetőséget az aktív szabálykészlet megadásához a Visual Studio Code-ban. Nyomja le az Enter billentyűt.

Az aktív API-stíluskalauz beállítása után bármely OpenAPI- vagy AsyncAPI-alapú specifikációs fájl megnyitása helyi linting műveletet indít el a Visual Studio Code-ban. Az eredmények mind a szerkesztőben, mind a Problémák ablakban (Problémák megtekintése>vagy Ctrl+Shift+M) beágyazottan jelennek meg.

Kompatibilitástörő változásészlelés

Az API új verzióinak bevezetésekor fontos gondoskodni arról, hogy a bevezetett módosítások ne szegik meg az API korábbi verzióiban az API-felhasználókat. A Visual Studio Code-hoz készült Azure API Center-bővítmény megkönnyíti az Optika által működtetett OpenAPI-specifikációs dokumentumok kompatibilitástörő változásészlelését.

1. A Parancskatalógus megnyitásához használja a Ctrl+Shift+P billentyűparancsot. Írja be az Azure API Centert : Észleli a kompatibilitástörő változást , és nyomja le az Enter billentyűt.
2. Válassza ki az első összehasonlítandó API-specifikációs dokumentumot. Az érvényes beállítások közé tartoznak az API-központban található API-specifikációk, egy helyi fájl vagy a Visual Studio Code aktív szerkesztője.
3. Válassza ki a második, összehasonlítandó API-specifikációs dokumentumot. Az érvényes beállítások közé tartoznak az API-központban található API-specifikációk, egy helyi fájl vagy a Visual Studio Code aktív szerkesztője.

A Visual Studio Code egy diff nézetet nyit meg a két API-specifikáció között. A kompatibilitástörő változások a szerkesztőben és a Problémák ablakban is megjelennek (Problémák megtekintése>vagy Ctrl+Shift+M).

OpenAPI-specifikációs fájl létrehozása API-kódból

A GitHub Copilot és a Visual Studio Code Azure API Center bővítményének használatával hozzon létre egy OpenAPI-specifikációs fájlt az API-kódból. Kattintson a jobb gombbal az API-kódra, válassza a Lehetőségek közül a Copilot lehetőséget, és válassza az API-dokumentáció létrehozása lehetőséget. Ez létrehoz egy OpenAPI-specifikációs fájlt.

Az OpenAPI specifikációs fájl létrehozása és a pontosság ellenőrzése után regisztrálhatja az API-t az API-központban az Azure API Center: Register API paranccsal.

API-k felfedezése

Az API-központ erőforrásai a bal oldali fanézetben jelennek meg. Az API-központ erőforrásainak kibontásával megtekintheti az API-kat, a verziókat, a definíciókat, a környezeteket és az üzembe helyezéseket.

API-k keresése egy API-központban az Apis fanézetelemben látható keresési ikonnal.

API-dokumentáció megtekintése

Megtekintheti egy API-definíció dokumentációját az API-központban, és kipróbálhatja az API-műveleteket. Ez a funkció csak openAPI-alapú API-khoz érhető el az API-központban.

1. Az API-definíció megjelenítéséhez bontsa ki az API Center fanézetét.

2. Kattintson a jobb gombbal a definícióra, és válassza az API-dokumentáció megnyitása parancsot. Megjelenik egy új lap az API-definíció Swagger felhasználói felületével.

   

3. Az API kipróbálásához válasszon ki egy végpontot, válassza a Kipróbálás lehetőséget, adja meg a szükséges paramétereket, és válassza a Végrehajtás lehetőséget.

   Feljegyzés

   Az API-tól függően előfordulhat, hogy meg kell adnia az engedélyezési hitelesítő adatokat vagy egy API-kulcsot az API kipróbálásához.

   Tipp.

   A bővítmény használatával api-dokumentációt is létrehozhat a Markdownban, amely könnyen karbantartható és megosztható a végfelhasználókkal. Kattintson a jobb gombbal a definícióra, és válassza a Markdown létrehozása lehetőséget.

HTTP-fájl létrehozása

A fájlokat .http az API-központ API-definíciója alapján tekintheti meg. Ha a REST-ügyfél bővítmény telepítve van, a Visual Studio Code-szerkesztőből is létrehozhat kérések könyvtárat. Ez a funkció csak openAPI-alapú API-khoz érhető el az API-központban.

1. Az API-definíció megjelenítéséhez bontsa ki az API Center fanézetét.

2. Kattintson a jobb gombbal a definícióra, és válassza a HTTP-fájl létrehozása lehetőséget. Megjelenik egy új lap, amely megjeleníti az API-specifikáció által kitöltött .http-dokumentumot.

   

3. Ha kérést szeretne küldeni, válasszon ki egy végpontot, és válassza a Kérés küldése lehetőséget.

   Feljegyzés

   Az API-tól függően előfordulhat, hogy meg kell adnia az engedélyezési hitelesítő adatokat vagy egy API-kulcsot a kérés elvégzéséhez.

API-ügyfél létrehozása

A Microsoft Kiota bővítmény használatával hozzon létre egy API-ügyfelet a kedvenc nyelvéhez. Ez a funkció csak openAPI-alapú API-khoz érhető el az API-központban.

1. Az API-definíció megjelenítéséhez bontsa ki az API Center fanézetét.
2. Kattintson a jobb gombbal a definícióra, és válassza az API-ügyfél létrehozása lehetőséget. Megjelenik a Kiota OpenAPI Generator panel.
3. Válassza ki az SDK-kba felvenni kívánt API-végpontokat és HTTP-műveleteket.
4. Válassza az API-ügyfél létrehozása lehetőséget.

   1. Adja meg az SDK nevével, névterével és kimeneti könyvtárával kapcsolatos konfigurációs adatokat.

   2. Válassza ki a létrehozott SDK nyelvét.

      

Az ügyfél létre lesz hozva.

A Kiota bővítmény használatáról további információt a Visual Studio Code Microsoft Kiota bővítményében talál.

API-specifikáció exportálása

Exportálhat egy API-specifikációt egy definícióból, majd letöltheti fájlként.

Specifikáció exportálása a bővítmény fanézetében:

1. Az API-definíció megjelenítéséhez bontsa ki az API Center fanézetét.

2. Kattintson a jobb gombbal a definícióra, és válassza az API specifikációs dokumentum exportálása lehetőséget. Megjelenik egy új lap, amely egy API-specifikációs dokumentumot jelenít meg.

   

A parancskatalógus használatával is exportálhat specifikációt:

1. Írja be a Ctrl+Shift+P billentyűparancsot a parancskatalógus megnyitásához.
2. Válassza az Azure API Center: API specifikációs dokumentum exportálása lehetőséget.
3. Válasszon egy API-definícióhoz való navigáláshoz. Megjelenik egy új lap, amely egy API-specifikációs dokumentumot jelenít meg.

Kapcsolódó tartalom

• Azure API Center – alapfogalmak