Začínáme s centrem rozhraní API

  • 10 min

V tomto cvičení:

  1. Vytvořte službu API Center.

  2. Definujte vlastnosti metadat.

  3. Přidejte rozhraní API do centra rozhraní API.

  4. Přidejte nasazení a prostředí.

Požadavky

Pokud chcete začít spravovat rozhraní API prostřednictvím služby API Center, potřebujete:

  1. Předplatné Azure.
  2. Poskytovatel prostředků Microsoft.ApiCenter zaregistrovaný ve vašem předplatném.
  3. Alespoň přiřazení role přispěvatele nebo ekvivalentní oprávnění v předplatném Azure.

Poznámka:

Pokud jste to ještě neudělali, musíte ve svém předplatném zaregistrovat poskytovatele prostředků Microsoft.ApiCenter .

  1. Přihlaste se k webu Azure Portal.
  2. Do vyhledávacího panelu zadejte předplatná .
  3. Vyberte předplatné, ve kterém chcete vytvořit centrum rozhraní API.
  4. V nabídce vlevo v části Prostředky vyberte Poskytovatele prostředků.
  5. V seznamu poskytovatelů prostředků vyhledejte Microsoft.ApiCenter . Pokud není zaregistrovaný, vyberte Zaregistrovat.

Krok 1: Vytvoření služby API Center

  1. Přihlaste se k webu Azure Portal.

  2. Na panelu hledání zadejte centra rozhraní API.

  3. Vyberte + Vytvořit.

  4. Na kartě Základy vyberte nebo zadejte následující nastavení:

    a. Vyberte své předplatné Azure.

    b. Vyberte existující skupinu prostředků nebo vyberte Nový a vytvořte novou.

    c. Zadejte název centra rozhraní API. Musí být jedinečný v oblasti, ve které vytváříte centrum rozhraní API.

    d. V oblasti vyberte jednu z dostupných oblastí pro Centrum rozhraní API.

    e. Pro cenový plán vyberte bezplatnou zkušební verzi (0 USD po dobu 90 dnů).

    f. Vyberte Zkontrolovat a vytvořit.

    h. Po dokončení ověření vyberte Vytvořit.

    Po nasazení je vaše centrum rozhraní API připravené k použití. Snímek obrazovky znázorňující úspěšné vytvoření instance služby API Center

Pokud chcete spustit referenční příkazy rozhraní příkazového řádku místně, nainstalujte Azure CLI a přihlaste se pomocí následujícího příkazu.

az login

Poznámka:

Pokud jste to ještě neudělali, musíte ve svém předplatném zaregistrovat poskytovatele prostředků Microsoft.ApiCenter .

Spuštěním následujícího příkazu zaregistrujte poskytovatele prostředků.

az provider register –namespace Microsoft.ApiCenter

Krok 1: Vytvoření služby API Center

Vytvořte skupinu prostředků spuštěním následujícího příkazu, který předá:

  • název skupiny prostředků --name Example. Contoso
  • location --location Example. Eastus
az group create –-name contoso –-location eastus

Snímek obrazovky znázorňující úspěšný příkaz az group create CLI

Poznámka:

az apic commands require the apic-extension Azure CLI extension extension. Pokud jste nepoužívali příkazy az apic , rozšíření se při spuštění prvního příkazu az apic nainstaluje dynamicky nebo můžete rozšíření nainstalovat ručně. Přečtěte si další informace o rozšířeních Azure CLI.

Spuštěním následujícího příkazu vytvořte centrum rozhraní API a předáte následující příkaz:

  • Příklad názvu služby api center -n contoso-apis
  • Příklad skupiny prostředků -g Contoso
  • umístění --l Example. Eastus
az apic create -n contoso-apis -g contoso -l eastus

Poznámka:

Ve výchozím nastavení se Centrum rozhraní API vytvoří v rámci cenové úrovně Free.

Poznámka:

Vytváření služby API Center se v současné době ve VS Code nepodporuje. Vytvořte ho pomocí Azure CLI nebo webu Azure Portal.

Krok 2: Definování vlastností metadat

Api Center používá vlastnosti metadat k uspořádání rozhraní API v inventáři a povolení operací, jako je filtrování, vyhledávání atd.

Poznámka:

Do názvů a názvů vlastností metadat nezahrnujte žádné citlivé, důvěrné ani osobní údaje.

Contoso, stejně jako mnoho dalších organizací by chtělo, aby všechna jejich rozhraní API prošla schvalovatelem, než budou k dispozici pro použití, a zajistili, že se pro všechna rozhraní API provádí kontrola dodržování předpisů. Organizace má také rozhraní API, která jsou veřejně přístupná a která jsou vytvořená výhradně pro interní použití. Pokud to chcete vynutit ve velkém měřítku napříč všemi rozhraními API, přidáme tři vlastní vlastnosti metadat:

  • Schvalovatel rozhraní API typu String
  • Kontrola dodržování předpisů předdefinovaných voleb typu
  • Veřejný přístup typu Boolean

  1. V nabídce vlevo vyberte Metadata assetů > a nová metadata > .Snímek obrazovky znázorňující postup přidání nových metadat na webu Azure Portal

  2. Na kartě Podrobnosti zadejte informace o vlastnosti.

    a. V nadpisu zadejte schvalovatele rozhraní API.

    b. V popisu zadejte výchozí schvalovatele rozhraní API.

    c. Vyberte typ Řetězec a vyberte Další.

  3. Na kartě Zadání vyberte Požadované pro rozhraní API. Vyberte volitelné pro nasazení a prostředí. Vyberte Další.

  4. Vyberte příkaz Vytvořit.

  5. Stejný postup opakujte u veřejné vlastnosti, jak je znázorněno na následujícím obrázku. Jako typ vyberte logickou hodnotu.

  6. Na kartě Zadání vyberte Požadované pro rozhraní API. Vyberte Nepoužitelné pro nasazení a prostředí. Vyberte Další.

  7. Vyberte příkaz Vytvořit.

  8. Stejný postup opakujte u vlastnosti Kontrola dodržování předpisů , jak je znázorněno na následujícím obrázku. Jako typ vyberte předdefinované volby a přidejte 3 volby, Nezačíná, Probíhá a Dokončeno.

  9. Na kartě Zadání vyberte Požadované pro rozhraní API. Vyberte Nepoužitelné pro nasazení a prostředí.

  10. Vyberte Další.

Schéma metadat JSON pro vaše rozhraní API je teď k dispozici k zobrazení, úpravám a stahování. Chcete-li zobrazit, vyberte Zobrazit schéma metadat a v rozevíracím seznamu vyberte rozhraní API .

Otevře se modální na pravé straně s podrobnostmi metadat, mezi které patří předdefinované vlastnosti z Centra rozhraní API, jako jsou LifecycleStage, Name, Description, TermsOfService. Pokud se posunete na konec souboru, uvidíte vlastní metadata, která jste přidali v předchozích krocích, jak je znázorněno níže. Snímek obrazovky znázorňující postup zobrazení schématu metadat na webu Azure Portal

Poznámka:

Vlastnosti ve schématu můžete kdykoli přidat a upravit a okamžitě je použít pro všechna rozhraní API ve vašem Centru rozhraní API.

Spuštěním následujícího příkazu vytvořte nové schéma metadat a nastavte:

  • Název metadat jako schvalovatel rozhraní API
  • Schéma s typem vlastnosti jako String a title jako schvalovatel rozhraní API
  • Přiřazení podle potřeby pro rozhraní API, která jsou volitelná pro prostředí a nasazení
az apic metadata create -g contoso -n contoso-apis --metadata-name "api-approver" --schema '{"type":"string","title":"API Approver"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Stejný postup opakujte pro:

  • Název metadat jako veřejně přístupný
  • Schéma s typem vlastnosti jako logická hodnota a název jako veřejně přístupný
  • Přiřazení podle potřeby pro rozhraní API, která jsou volitelná pro prostředí a nasazení

Spuštěním následujícího příkazu:

az apic metadata create -g contoso -n contoso-apis --metadata-name "public-facing" --schema '{"type":"boolean", "title":"Public Facing"}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Nakonec zopakujte stejné kroky pro:

  • Název metadat jako kontrola dodržování předpisů
  • Schéma s typem vlastnosti jako String a title as Compliance Review
  • Přiřazení podle potřeby pro rozhraní API, která jsou volitelná pro prostředí a nasazení

Spuštěním následujícího příkazu:

az apic metadata create -g contoso -n contoso-apis --metadata-name "compliance-review" --schema '{"type":"string","title":"Compliance Review", "oneOf":[{"const":"Not Started","description":""},{"const":"In Progress","description":""},{"const":"Completed","description":""}]}' --assignments '[{entity:api,required:true,deprecated:false},{entity:environment,required:true,deprecated:false}]'

Spuštěním následujícího příkazu můžete zobrazit seznam všech definovaných metadat v Centru rozhraní API.

az apic metadata list -g <resource-group-name> -n <api-center-name>

Poznámka:

Vlastnosti ve schématu můžete kdykoli přidat a upravit a okamžitě je použít pro všechna rozhraní API ve vašem Centru rozhraní API.

Poznámka:

Tato akce se v nástroji VS Code v současné době nepodporuje. Vytvořte ho pomocí Azure CLI nebo webu Azure Portal.

Krok 3: Přidání rozhraní API do inventáře

Organizace Contoso by chtěla doporučit technické konference pro své technické týmy jako součást své interní dovednosti. Přidáme rozhraní API konference s mluvčími, relacemi a tématy.

V následujících krocích můžete zkopírovat definici OpenAPI z výše uvedeného webu a uložit ji jako soubor JSON na místním počítači. Nebo při přidávání rozhraní API do inventáře nahraďte jinou definici rozhraní API.

  1. Na portálu přejděte do centra rozhraní API.

  2. V nabídce vlevo vyberte rozhraní API > prostředků > a zaregistrovat rozhraní API.Snímek obrazovky znázorňující postup přidání nového rozhraní API na webu Azure Portal

  3. Na stránce Zaregistrovat rozhraní API přidejte následující požadované informace pro rozhraní API. V dolní části stránky se zobrazí vlastní vlastnosti schvalovatele rozhraní API, *Veřejně přístupné a metadata kontroly dodržování předpisů, které jste definovali v předchozích krocích. OBRÁZEK GIF znázorňující postup registrace nového rozhraní API na webu Azure Portal

Pokud chcete zobrazit vytvořené rozhraní API, vyberte v nabídce vlevo rozhraní API pro konference Assets >> API.

Karta Přehled poskytuje zobrazení konfigurace rozhraní API. Rozbalením podrobností zobrazíte a upravíte další informace, jako jsou verze rozhraní API a nasazení (v tuto chvíli nemáme žádná nasazení).

Obvykle byste chtěli přidat definici rozhraní API pro vaši verzi rozhraní API a centrum API podporuje formáty specifikace textu, včetně OpenAPI 2, OpenAPI 3 pro REST.

Pokud chcete přidat definici,

  1. V nabídce vlevo vyberte rozhraní API > pro prostředky > a vyberte vaše rozhraní API (Conference API).
  2. Rozbalte podrobnosti a vyberte Verze.
  3. Vyberte svou verzi (v1) a rozbalte podrobnosti.
  4. V části Podrobnosti vyberte Definice > Přidat definici. Snímek obrazovky znázorňující postup přidání definice rozhraní API na webu Azure Portal

K registraci rozhraní API do instance rozhraní API můžete použít rozšíření Azure API Center pro Visual Studio Code.

Krok 1:Instalace rozšíření

Krok 2: Otevřete paletu příkazů Ctrl + Shift + P a zadejte API Center: Registrace rozhraní API

Postupujte podle pokynů a zadejte následující informace pro vaše rozhraní API:

Registrace rozhraní API Podrobný postup
Výběr služby API Center Výběr instance služby API Center
Název rozhraní API Zadejte název rozhraní API (Conference API).
Typ rozhraní API REST
Název verze rozhraní API Zadejte název verze pro vaše rozhraní API (v1).
Životní cyklus verze rozhraní API V rozevíracím seznamu (Vývoj) vyberte životní cyklus.
Název definice rozhraní API Zadejte název definice (definice rozhraní API konference).
Název specifikace rozhraní API V rozevíracím seznamu vyberte specifikaci (OpenAPI 2).
Výběr definičního souboru rozhraní API pro import Procházení a výběr definičního souboru z úložiště

Snímek obrazovky znázorňující postup registrace rozhraní API ve VS Code

Aktualizujte kartu rozšíření api Center a nově vytvořené rozhraní API se zobrazí v příslušné instanci nebo prostředku APIC.

Pomocí následujícího příkazu vytvořte nové rozhraní API a předáte ho:

  • Příklad skupiny prostředků -g Contoso
  • Příklad názvu služby api center -n contoso-api-center
  • Název --název Příklad. Rozhraní API konference
  • PŘÍKLAD ID rozhraní API --api-id . conference-api
  • Zadejte příklad --type . REST
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST

Pomocí následujícího příkazu vytvořte verzi rozhraní API a předáte ji:

  • Příklad skupiny prostředků -g contoso
  • Příklad názvu služby api center -n contoso-apis
  • PŘÍKLAD ID rozhraní API --api-id . conference-api
  • Název --název Příklad. v1.2.2
  • Příklad ID verze --version-id . 2024-07-03
  • Fáze životního cyklu – příklad fáze životního cyklu navrhnout
az apic api version create -g contoso -n contoso-apis --api-id conference-api --title v1.2.2 --version-id 2024-07-03 --lifecycle-stage design

Můžete také přidat definici rozhraní API pro vaši verzi rozhraní API a centrum API podporuje formáty specifikace textu, včetně OpenAPI 2, OpenAPI 3 pro REST.

Pokud chcete přidat definici, použijte následující příkaz, který předá:

  • Příklad skupiny prostředků -g contoso
  • Příklad názvu služby api center -n contoso-apis
  • PŘÍKLAD ID rozhraní API --api-id . conference-api
  • Příklad ID verze --version-id . 2024-07-03
  • Název --název Příklad. OpenAPI
  • ID definice --definition-id Příklad. openapi
az apic api definition create -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --title OpenAPI --definition-id openapi

K importu definičního souboru OpenAPI z adresy URL použijte příkaz az apic api definition import-specification . Příklad: https://learn.microsoft.com/cli/azure/apic/api/definition?view=azure-cli-latest#az-apic-api-definition-import-specification-examples

az apic api definition import-specification -g contoso -n contoso-apis --api-id conference-api --version-id 2024-07-03 --definition-id openapi --format "link" --value 'https://petstore3.swagger.io/api/v3/openapi.json' --specification '{"name":"openapi","version":"3.0.2"}'

Krok 4: Přidání nasazení a prostředí

Prostředí

Prostředí (vývoj, testování, příprava nebo produkční prostředí) představuje umístění, kde je nasazen modul runtime rozhraní API. Technici platformy API ve společnosti Contoso definují dvě prostředí – testování a produkční prostředí– v instanci centra API pro správu a sledování různých modulů runtime api ve své organizaci.

Pokud chcete vytvořit prostředí,

  1. V nabídce vlevo vyberte Prostředí > prostředků > + Nové prostředí.

  2. Zadejte následující informace. Snímek obrazovky znázorňující postup vytvoření nového prostředí na webu Azure Portal

  3. Vyberte Vytvořit.

  4. Stejný postup opakujte pro produkční prostředí.

    Snímek obrazovky znázorňující postup vytvoření nového prostředí produkčního typu na webu Azure Portal

Pokud chcete vytvořit prostředí, spusťte následující příkaz rozhraní příkazového řádku.

az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing

Stejný postup opakujte pro produkční prostředí.

az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production

Poznámka:

Vytváření prostředí se v nástroji VS Code v současné době nepodporuje. Pro tento krok použijte Azure CLI nebo možnost webu Azure Portal.

Nasazení

Pro každý modul runtime rozhraní API v daném prostředí se poskytuje jedinečné umístění (adresa) pro uživatele, kteří budou s vaším rozhraním API pracovat. Toto umístění se nazývá nasazení a jedna verze rozhraní API může mít dvě nasazení – přípravné a produkční nasazení.

Contoso má jedno rozhraní API, rozhraní API konference, které přidružíme k prostředím, která jsme vytvořili.

  1. Na portálu přejděte do centra rozhraní API.

  2. V nabídce vlevo vyberte rozhraní API a pak vyberte rozhraní API, například rozhraní API konference.

  3. Na stránce rozhraní API konference rozbalte podrobnosti >nasazení > a přidejte nasazení.

  4. Přidejte následující informace:

    a. V rozevíracím seznamu pro pole Prostředí vyberte Testování společnosti Contoso.

    b. U definice klikněte na Vybrat, v rozevíracím seznamu zvolte verzi rozhraní API v1 a vyberte definici, kterou jste přidali dříve. Klepněte na tlačítko Vybrat.

    c. Po úspěšném přidání definice přidejte základní adresu URL modulu runtime, která bude specifická pro rozhraní API ve vybraném prostředí.

    Snímek obrazovky znázorňující postup vytvoření nového nasazení na webu Azure Portal

Pokud chcete vytvořit nasazení a přidružit ho k prostředí, které jsme vytvořili v předchozím kroku, spusťte následující příkaz rozhraní příkazového řádku.

az apic api deployment create -g contoso-corporation -s contoso-api-center --deployment-id "v1-conference-api" --title "Conference OpenAPI 2" --description "Conference Demo API deployment." --api-id conference-api --environment-id "/workspaces/default/environments/contoso-testing" --definition-id "/workspaces/default/apis/conference-api/versions/v1/definitions/conference-openapi-2" --server '{"runtimeUri":["https://conferenceapi.azurewebsites.net/"]}'

Snímek obrazovky znázorňující příkaz rozhraní příkazového řádku pro vytvoření nasazení

Poznámka:

Vytváření nasazení se v nástroji VS Code v současné době nepodporuje. Pro tento krok použijte Azure CLI nebo možnost webu Azure Portal.