Kom igång med API Center

  • 10 minuter

I den här övningen kommer du att:

  1. Skapa en API Center-tjänst.

  2. Definiera metadataegenskaper.

  3. Lägg till API:er i API Center.

  4. Lägg till distributioner och miljöer.

Förutsättningar

Om du vill börja hantera dina API:er via API Center behöver du:

  1. En Azure-prenumeration
  2. Microsoft.ApiCenter-resursprovidern som är registrerad i din prenumeration.
  3. Minst en rolltilldelning för deltagare eller motsvarande behörigheter i Azure-prenumerationen.

Kommentar

Om du inte redan har gjort det måste du registrera resursprovidern Microsoft.ApiCenter i din prenumeration.

  1. Logga in på Azure-portalen .
  2. Ange Prenumerationer i sökfältet.
  3. Välj en prenumeration där du vill skapa API Center.
  4. I den vänstra menyn går du till Resurser och väljer Resursprovidrar.
  5. Sök efter Microsoft.ApiCenter i listan över resursprovidrar. Om den inte är registrerad väljer du Registrera.

Steg 1: Skapa en API Center-tjänst

  1. Logga in på Azure-portalen .

  2. Ange API Centers i sökfältet.

  3. Välj + Skapa.

  4. Välj eller ange följande inställningar på fliken Grundläggande :

    a. Välj din Azure-prenumerationen.

    b) Välj en befintlig resursgrupp eller välj Ny för att skapa en ny.

    c. Ange ett namn för ditt API-center. Den måste vara unik i den region där du skapar ditt API-center.

    d. I Region väljer du en av de tillgängliga regionerna för API Center.

    e. För prisplanen väljer du Kostnadsfri utvärderingsversion (0 USD i 90 dagar).

    f. Välj Granska + skapa.

    h. När valideringen är klar väljer du Skapa.

    Efter distributionen är api-centret redo att användas! Skärmbild som visar att API Center-instansen har skapats.

Om du vill köra CLI-referenskommandon lokalt installerar du Azure CLI och loggar in med följande kommando.

az login

Kommentar

Om du inte redan har gjort det måste du registrera resursprovidern Microsoft.ApiCenter i din prenumeration.

Kör följande kommando för att registrera resursprovidern

az provider register –namespace Microsoft.ApiCenter

Steg 1: Skapa en API Center-tjänst

Skapa en resursgrupp genom att köra följande kommando som skickar:

  • resursgruppnamn --name Exempel. Contoso
  • plats --plats Exempel. Eastus
az group create –-name contoso –-location eastus

Skärmbild som visar det framgångsrika kommandot az group create CLI

Kommentar

az apic-kommandon kräver tillägget apic-extension för Azure CLI. Om du inte har använt az apic-kommandon installeras tillägget dynamiskt när du kör ditt första az apic-kommando , eller så kan du installera tillägget manuellt. Läs mer om Azure CLI-tillägg.

Skapa ett API Center genom att köra följande kommando och skicka:

  • API Center-tjänstnamn -n Exempel. contoso-apis
  • Resursgrupp –g Exempel. Contoso
  • location --l Exempel. Eastus
az apic create -n contoso-apis -g contoso -l eastus

Kommentar

Som standard skapas API Center under prisnivån Kostnadsfri.

Kommentar

Det går för närvarande inte att skapa en API Center-tjänst i VS Code. Skapa en med Hjälp av Azure CLI eller Azure Portal.

Steg 2: Definiera metadataegenskaper

API Center använder metadataegenskaper för att organisera API:erna i din inventering och aktivera åtgärder som filtrering, sökning osv.

Kommentar

Inkludera inte känslig, konfidentiell eller personlig information i metadataegenskapernas rubriker/namn.

Contoso, precis som många andra organisationer, vill att alla deras API:er ska passera genom en godkännare innan de blir tillgängliga för användning och se till att en efterlevnadsgranskning utförs för alla API:er. Organisationen har också API:er som är offentliga och som endast har skapats för internt bruk. För att framtvinga detta i stor skala för alla API:er lägger vi till tre anpassade metadataegenskaper:

  • API-godkännare av typen Sträng
  • Efterlevnadsgranskning av typen Fördefinierade alternativ
  • Offentligt tillgänglig av typen Boolesk

  1. På den vänstra menyn väljer du Tillgångar Metadata >> + Nya metadata.Skärmbild som visar steg för att lägga till nya metadata på Azure-portalen

  2. På fliken Information anger du information om egenskapen.

    a. I titelfältet anger du API-godkännare

    b) I Beskrivning anger du Standard-API-godkännare

    c. Välj typ Sträng och välj Nästa

  3. På fliken Tilldelningar väljer du Obligatoriskt för API:er. Välj Valfritt för Distributioner och miljöer. Välj Nästa

  4. Välj Skapa

  5. Upprepa samma steg för egenskapen Offentlig som visas i bilden nedan. För typ väljer du Booleskt värde

  6. På fliken Tilldelningar väljer du Obligatoriskt för API:er. Välj Inte tillämpligt för Distributioner och miljöer. Välj Nästa

  7. Välj Skapa

  8. Upprepa samma steg för egenskapen Efterlevnadsgranskning som visas i bilden nedan. För typen väljer du Fördefinierade alternativ och lägger till 3 alternativ, Inte startad, Pågår och Slutförd

  9. På fliken Tilldelningar väljer du Obligatoriskt för API:er. Välj Inte tillämpligt för distributioner och miljöer

  10. Välj Nästa

Ett JSON-metadataschema för dina API:er är nu tillgängligt för dig att visa, redigera och ladda ned. Om du vill visa väljer du Visa metadataschema och väljer API:er i listrutan.

Detta öppnar en modal till höger med metadatainformation, som inkluderar inbyggda egenskaper från API Center, till exempel LifecycleStage, Name, Description, TermsOfService med flera. Om du bläddrar längst ned i filen visas de anpassade metadata som du har lagt till i föregående steg enligt nedan. Skärmbild som visar steg för att visa metadataschema på Azure-portalen

Kommentar

Du kan lägga till och redigera egenskaper i schemat när som helst och omedelbart tillämpa dem på alla API:er i API Center

Skapa ett nytt metadataschema genom att köra följande kommando för att ange:

  • Metadatanamn som api-godkännare
  • Schema med egenskapstyp som Sträng och rubrik som API-godkännare
  • Tilldelningarsom krävs för API:er medan de är valfria för Miljö och Distribution
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}]'

Upprepa samma steg för:

  • Metadatanamn som offentligt synligt
  • Schema med egenskapstyp som Boolean och titel som Offentlig Yta
  • Tilldelningarsom krävs för API:er medan de är valfria för Miljö och Distribution

Genom att köra följande kommando:

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}]'

Upprepa slutligen samma steg för:

  • Metadatanamn som efterlevnadsgranskning
  • Schema med egenskapstyp som Sträng och rubrik som efterlevnadsgranskning
  • Tilldelningarsom krävs för API:er medan de är valfria för Miljö och Distribution

Genom att köra följande kommando:

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}]'

Du kan köra följande kommando för att visa en lista över alla definierade metadata i API Center.

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

Kommentar

Du kan lägga till och redigera egenskaper i schemat när som helst och omedelbart tillämpa dem på alla API:er i API Center

Kommentar

Den här åtgärden stöds för närvarande inte i VS Code. Skapa en med Hjälp av Azure CLI eller Azure Portal.

Steg 3: Lägga till API:er i lagret

Contoso-organisationen vill rekommendera tekniska konferenser för sina tekniska team som en del av deras interna kompetensutveckling. Vi lägger till ett konferens-API med talare, sessioner och ämnen.

För följande steg kan du kopiera OpenAPI-definitionen från webbplatsen ovan och spara den som en JSON-fil på den lokala datorn. Alternativt kan du ersätta en annan API-definition när du lägger till ett API i inventeringen.

  1. Gå till API-centret i portalen.

  2. I den vänstra menyn väljer du Tillgångar > API:er > + Registrera API.Skärmbild som visar steg för att lägga till ett nytt API på Azure-portalen

  3. På sidan Registrera API lägger du till följande information som krävs för API:et. Du ser de anpassade metadataegenskaperna för API-godkännare, offentligt tillgänglig och efterlevnadsgranskning som du definierade i föregående steg längst ned på sidan. GIF som visar steg för att registrera ett nytt API på Azure-portalen

Om du vill visa det skapade API:et går du till den vänstra menyn och väljer >:er>.

Fliken Översikt visar en vy över API-konfigurationen. Expandera Information för att se och redigera ytterligare information, till exempel API-version och distributioner (vi har inga distributioner just nu).

Du skulle normalt vilja lägga till en API-definition för din API-version och API Center stöder textspecifikationsformat, inklusive OpenAPI 2, OpenAPI 3 för REST.

Om du vill lägga till en definition,

  1. I den vänstra menyn väljer du Tillgångar > API:er > Välj ditt API (konferens-API).
  2. Expandera Information och välj Versioner.
  3. Välj din version (v1) och expandera Information.
  4. Under Information väljer du Definitioner > Lägg till definition. Skärmbild som visar steg för att lägga till en API-definition på Azure-portalen

Du kan använda Azure API Center-tillägget för Visual Studio Code för att registrera ett API i din API-instans.

Steg 1:Installera tillägget

Steg 2: Öppna kommandopaletten Ctrl + Skift + P och skriv API Center: Registrera API

Följ anvisningarna för att ange följande information för ditt API:

Registrera API Steg-för-steg
Välj API Center-tjänst Välj din API Center-instans
API-rubrik Ange namnet på ditt API (konferens-API)
API-typ VILA
API-versionsrubrik Ange ett versionsnamn för ditt API (v1)
Livscykel för API-version Välj en livscykel i listrutan (Utveckling)
API-definitionsrubrik Ange ett namn för din definition (Conference API Definition)
API-specifikationsnamn Välj en specifikation i listrutan (OpenAPI 2)
Välj API-definitionsfil som ska importeras Bläddra och välj definitionsfilen från lagringen

Skärmbild som visar steg för att registrera ett API i VS Code

Uppdatera fliken API Center-tillägg så visas ditt nyligen skapade API i respektive APIC-instans/resurs.

Använd följande kommando för att skapa ett nytt API som skickar följande:

  • Resursgrupp –g Exempel. Contoso
  • API Center-tjänstnamn -n Exempel. contoso-api-center
  • Rubrik --title Exempel. Konferens-API
  • API-ID --api-id Exempel. conference-api
  • Typ - typ Exempel. VILA
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST

Skapa en API-version med följande kommando och skicka följande:

  • Resursgrupp –g Exempel. contoso
  • API Center-tjänstnamn -n Exempel. contoso-apis
  • API-ID --api-id Exempel. conference-api
  • Rubrik --title Exempel. v1.2.2
  • Versions-ID --version-id Exempel. 2024-07-03
  • Livscykelsteg – exempel på livscykelsteg . design
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

Du kan också lägga till en API-definition för din API-version och API Center stöder textspecifikationsformat, inklusive OpenAPI 2, OpenAPI 3 för REST.

Om du vill lägga till en definition använder du följande kommando och skickar in:

  • Resursgrupp –g Exempel. contoso
  • API Center-tjänstnamn -n Exempel. contoso-apis
  • API-ID --api-id Exempel. conference-api
  • Versions-ID --version-id Exempel. 2024-07-03
  • Rubrik --title Exempel. OpenAPI
  • Definitions-ID --definition-id Exempel. 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

Om du vill importera en OpenAPI-definitionsfil från en URL använder du kommandot az apic api definition import-specification för att importera . Exempel: 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"}'

Steg 4: Lägga till distributioner och miljöer

Miljöer

En miljö (utveckling, testning, mellanlagring eller produktion) representerar en plats där en API-körning distribueras. API Platform-tekniker på Contoso definierar två miljöer – testning och produktion i sin API Center-instans för att hantera och spåra olika API-körningar i organisationen.

Skapa en miljö genom att

  1. På den vänstra menyn väljer du Tillgångar > Miljöer > + Ny miljö.

  2. Lägg till följande information. Skärmbild som visar steg för att skapa en ny miljö på Azure-portalen

  3. Välj Skapa.

  4. Upprepa samma steg för produktionsmiljön.

    Skärmbild som visar steg för att skapa en ny miljö av produktionstyp på Azure-portalen

Om du vill skapa en miljö kör du följande CLI-kommando

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

Upprepa samma sak för produktionsmiljön

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

Kommentar

Det går för närvarande inte att skapa miljöer i VS Code. Använd Azure CLI eller alternativet Azure Portal för det här steget.

Distributioner

En unik plats (adress) för användare att interagera med ditt API tillhandahålls för varje API-körning i en viss miljö. Den här platsen kallas för distribution och en enda API-version kan ha två distributioner – en mellanlagring och en produktionsdistribution.

Contoso har ett API, konferens-API:et, som vi associerar med de miljöer vi skapade.

  1. Gå till API-centret i portalen.

  2. I den vänstra menyn väljer du API:er och sedan ett API, till exempel konferens-API:et.

  3. På Konferens-API-sidan expanderar du Detaljer > Driftsättningar > + Lägg till driftsättning.

  4. Lägg till följande information:

    a. Välj Contoso-testning i listrutan för fältet Miljö .

    b) För definitionen klickar du på Välj, väljer API-version v1 i listrutan och väljer den definition som du lade till tidigare. Klicka på Välj.

    c. När du har lagt till definitionen lägger du till en grundläggande körnings-URL som är specifik för API:et i den valda miljön.

    Skärmbild som visar steg för att skapa en ny distribution på Azure-portalen

Om du vill skapa en distribution och associera den med miljön som vi skapade i steget ovan kör du följande CLI-kommando

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/"]}'

Skärmbild som visar CLI-kommandot för att skapa en distribution

Kommentar

Det går för närvarande inte att skapa distributioner i VS Code. Använd Azure CLI eller alternativet Azure Portal för det här steget.