Aan de slag met API Center
In deze oefening gaat u het volgende doen:
Maak een API Center-service.
Eigenschappen van metagegevens definiëren.
VOEG API's toe aan uw API Center.
Implementaties en omgevingen toevoegen.
Vereisten
Als u uw API's via API Center wilt beheren, hebt u het volgende nodig:
- Een Azure-abonnement.
- De Microsoft.ApiCenter-resourceprovider die is geregistreerd in uw abonnement.
- Ten minste een roltoewijzing inzender of gelijkwaardige machtigingen in het Azure-abonnement.
Notitie
Als u dat nog niet hebt gedaan, moet u de Resourceprovider Microsoft.ApiCenter registreren in uw abonnement.
- Meld u aan bij de Azure-portal.
- Voer Abonnementen in de zoekbalk in.
- Selecteer het abonnement waarin u het API Center wilt maken.
- Selecteer resourceproviders in het linkermenu onder Resources.
- Zoek naar Microsoft.ApiCenter in de lijst met resourceproviders. Als deze niet is geregistreerd, selecteert u Registreren.
Stap 1: Een API Center-service maken
Voer API-centra in de zoekbalk in.
Selecteer + Maken.
Selecteer of voer op het tabblad Basis de volgende instellingen in:
a. Selecteer uw Azure-abonnement.
b. Selecteer een bestaande resourcegroep of selecteer Nieuw om een nieuwe te maken.
c. Voer een naam in voor uw API-centrum. Deze moet uniek zijn in de regio waar u uw API-centrum maakt.
d. Selecteer in Regio een van de beschikbare regio's voor API Center.
e. Voor het prijsplan selecteert u gratis proefversie ($ 0 voor 90 dagen).
f. Selecteer Controleren + maken.
h. Nadat de validatie is voltooid, selecteert u Maken.
Na de implementatie is uw API-centrum klaar voor gebruik.
Als u CLI-referentieopdrachten lokaal wilt uitvoeren, installeert u de Azure CLI en meldt u zich aan met behulp van de volgende opdracht.
az login
Notitie
Als u dat nog niet hebt gedaan, moet u de Resourceprovider Microsoft.ApiCenter registreren in uw abonnement.
Voer de volgende opdracht uit om de resourceprovider te registreren
az provider register –namespace Microsoft.ApiCenter
Stap 1: Een API Center-service maken
Maak een resourcegroep door de volgende opdracht door te geven:
- resourcegroepnaam --name Voorbeeld. Contoso
- location --location Example. Eastus
az group create –-name contoso –-location eastus
Notitie
az apic commands require the apic-extension Azure CLI extension. Als u az apic-opdrachten niet hebt gebruikt, wordt de extensie dynamisch geïnstalleerd wanneer u uw eerste az apic-opdracht uitvoert of kunt u de extensie handmatig installeren. Meer informatie over Azure CLI-extensies.
Maak een API Center door de volgende opdracht uit te voeren en de volgende opdracht door te geven:
- Servicenaam van API Center -n Voorbeeld. contoso-apis
- Voorbeeld van resourcegroep -g . Contoso
- location --l Example. Eastus
az apic create -n contoso-apis -g contoso -l eastus
Notitie
Standaard wordt het API Center gemaakt onder de prijscategorie Gratis.
Notitie
Het maken van een API Center-service wordt momenteel niet ondersteund in VS Code. Maak er een met behulp van Azure CLI of Azure Portal.
Stap 2: Eigenschappen van metagegevens definiëren
API Center maakt gebruik van metagegevenseigenschappen om de API's in uw inventaris te ordenen en bewerkingen zoals filteren, zoeken, enzovoort in te schakelen.
Notitie
Neem geen gevoelige, vertrouwelijke of persoonlijke gegevens op in de titels/namen van metagegevenseigenschappen.
Contoso, net als veel andere organisaties, willen al hun API's door een fiatteur laten passeren voordat ze beschikbaar zijn voor gebruik en ervoor zorgen dat er een nalevingsbeoordeling wordt uitgevoerd voor alle API's. De organisatie heeft ook API's die openbaar zijn en die uitsluitend zijn gebouwd voor intern gebruik. Als u dit op schaal wilt afdwingen voor alle API's, voegen we drie aangepaste metagegevenseigenschappen toe:
- API-fiatteur van het type Tekenreeks
- Nalevingsbeoordeling van vooraf gedefinieerde typen
- Openbaar gericht op het type Booleaanse waarde
Selecteer In het linkermenu Assets > Metadata > + New metadata.
Voer op het tabblad Details informatie over de eigenschap in.
a. Voer in Titel API-fiatteur in
b. Voer in beschrijving de standaard-API-fiatteur in
c. Selecteer tekenreeks en selecteer Volgende
Selecteer Vereist voor API's op het tabblad Toewijzingen. Selecteer Optioneel voor implementaties en omgevingen. Selecteer Volgende
Selecteer Maken.
Herhaal dezelfde stappen voor de eigenschap Openbaar , zoals wordt weergegeven in de onderstaande afbeelding. Selecteer Booleaanse waarde voor type
Selecteer Vereist voor API's op het tabblad Toewijzingen. Selecteer Niet van toepassing op implementaties en omgevingen. Selecteer Volgende
Selecteer Maken.
Herhaal dezelfde stappen voor de eigenschap Compliancebeoordeling , zoals wordt weergegeven in de onderstaande afbeelding. Voor het type selecteert u Vooraf gedefinieerde opties en voegt u 3 opties toe, Niet gestart, Wordt uitgevoerd en Voltooid
Selecteer Vereist voor API's op het tabblad Toewijzingen. Selecteer Niet van toepassing op implementaties en omgevingen
Selecteer Volgende
Er is nu een JSON-metagegevensschema voor uw API's beschikbaar om te bekijken, te bewerken en te downloaden. Als u wilt weergeven, selecteert u Het metagegevensschema weergeven en selecteert u API's in de vervolgkeuzelijst.
Hiermee opent u rechts een modaal bestand met metagegevensdetails, waaronder ingebouwde eigenschappen van API Center, zoals LifecycleStage, Name, Description, TermsOfService . Als u naar de onderkant van het bestand schuift, ziet u de aangepaste metagegevens die u in de vorige stappen hebt toegevoegd, zoals hieronder wordt weergegeven.
Notitie
U kunt op elk gewenst moment eigenschappen in het schema toevoegen en bewerken en deze direct toepassen op alle API's in uw API Center
Maak een nieuw metagegevensschema door de volgende opdracht uit te voeren om het volgende in te stellen:
- Naam van metagegevens als API-fiatteur
- Schema met eigenschapstype als tekenreeks en titel als API-fiatteur
- Toewijzingen zoals vereist voor API's , terwijl deze optioneel zijn voor omgeving en implementatie
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}]'
Herhaal dezelfde stappen voor:
- Naam van metagegevens als openbaar
- Schema met eigenschapstype als Booleaanse waarde en titel als Openbaar
- Toewijzingen zoals vereist voor API's , terwijl deze optioneel zijn voor omgeving en implementatie
Door de volgende opdracht uit te voeren:
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}]'
Herhaal tot slot dezelfde stappen voor:
- Naam van metagegevens als nalevingsbeoordeling
- Schema met eigenschapstype als tekenreeks en titel als nalevingsbeoordeling
- Toewijzingen zoals vereist voor API's , terwijl deze optioneel zijn voor omgeving en implementatie
Door de volgende opdracht uit te voeren:
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}]'
U kunt de volgende opdracht uitvoeren om een lijst met alle gedefinieerde metagegevens in uw API Center weer te geven.
az apic metadata list -g <resource-group-name> -n <api-center-name>
Notitie
U kunt op elk gewenst moment eigenschappen in het schema toevoegen en bewerken en deze direct toepassen op alle API's in uw API Center
Notitie
Deze actie wordt momenteel niet ondersteund in VS Code. Maak er een met behulp van Azure CLI of Azure Portal.
Stap 3: API's toevoegen aan de inventaris
De Contoso-organisatie wil technische conferenties aanbevelen voor hun technische teams als onderdeel van hun interne vaardigheden. We voegen een Conferentie-API toe met sprekers, sessies en onderwerpen.
URL van vergadering-API: https://bigconference.azurewebsites.net/
Voor de volgende stappen kunt u de OpenAPI-definitie van de bovenstaande website kopiëren en opslaan als een JSON-bestand op uw lokale computer. Of vervang een andere API-definitie wanneer u een API toevoegt aan de inventaris.
Navigeer in de portal naar uw API-centrum.
Selecteer in het linkermenu Assets-API's > > + API registreren.
Voeg op de pagina API registreren de volgende vereiste informatie voor de API toe. Onder aan de pagina ziet u de eigenschappen van de aangepaste API-fiatteur, *Openbaar en nalevingsbeoordeling die u in de vorige stappen hebt gedefinieerd.
Als u de gemaakte API wilt weergeven, selecteert u in het linkermenu Assets > API's Conference API's>.
Het tabblad Overzicht geeft een weergave van de API-configuratie. Vouw details uit om aanvullende informatie te bekijken en te bewerken, zoals API-versie en implementaties (er zijn op dit moment geen implementaties).
Normaal gesproken wilt u een API-definitie toevoegen voor uw API-versie en API Center ondersteunt indelingen voor tekstspecificaties, waaronder OpenAPI 2, OpenAPI 3 voor REST.
Een definitie toevoegen:
- Selecteer in het linkermenu Assets-API's > > Uw API (Conference-API) selecteren.
- Vouw Details uit en selecteer Versies.
- Selecteer uw versie (v1) en vouw Details uit.
- Selecteer definities > toevoegen onder details.
U kunt de Azure API Center-extensie voor Visual Studio Code gebruiken om een API te registreren bij uw API-exemplaar.
Stap 1: De extensie installeren
Stap 2: Open het opdrachtpallet, Ctrl + Shift + P en typ API Center: API registreren
Volg de aanwijzingen om de volgende informatie voor uw API op te geven:
| API registreren | Stapsgewijs |
|---|---|
| API Center-service selecteren | Selecteer uw API Center-exemplaar |
| API-titel | Voer de naam van uw API in (Conferentie-API) |
| Type API | REST |
| Titel van API-versie | Voer een versienaam in voor uw API (v1) |
| Levenscyclus van API-versie | Selecteer een levenscyclus in de vervolgkeuzelijst (Ontwikkeling) |
| Titel van API-definitie | Voer een naam in voor uw definitie (Conference API Definition) |
| Api-specificatienaam | Selecteer een specificatie in de vervolgkeuzelijst (OpenAPI 2) |
| Api-definitiebestand selecteren om te importeren | Blader en selecteer het definitiebestand in uw opslag |
Vernieuw het tabblad API Center-extensie en uw zojuist gemaakte API wordt weergegeven in de respectieve APIC-instantie/resource.
Gebruik de volgende opdracht om een nieuwe API te maken, waarbij de volgende opdracht wordt doorgegeven:
- Voorbeeld van resourcegroep -g . Contoso
- Servicenaam van API Center -n Voorbeeld. contoso-api-center
- Titel - titelvoorbeeld . Conferentie-API
- API-id --api-id-voorbeeld . conference-api
- Typ --type voorbeeld. REST
az apic api create -g contoso -n contoso-apis --title "Conference API" --api-id conference-api --type REST
Maak een API-versie met behulp van de volgende opdracht, waarbij de volgende opdracht wordt doorgegeven:
- Voorbeeld van resourcegroep -g . contoso
- Servicenaam van API Center -n Voorbeeld. contoso-apis
- API-id --api-id-voorbeeld . conference-api
- Titel - titelvoorbeeld . v1.2.2
- Versie-id --version-id Voorbeeld. 2024-07-03
- Levenscyclusfase - voorbeeld van levenscyclusfase . -ontwerp
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
U kunt ook een API-definitie toevoegen voor uw API-versie en API Center ondersteunt indelingen voor tekstspecificaties, waaronder OpenAPI 2, OpenAPI 3 voor REST.
Als u een definitie wilt toevoegen, gebruikt u de volgende opdracht en geeft u deze door:
- Voorbeeld van resourcegroep -g . contoso
- Servicenaam van API Center -n Voorbeeld. contoso-apis
- API-id --api-id-voorbeeld . conference-api
- Versie-id --version-id Voorbeeld. 2024-07-03
- Titel - titelvoorbeeld . OpenAPI
- Definitie-id --definition-id-voorbeeld . 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
Als u een OpenAPI-definitiebestand wilt importeren vanuit een URL, gebruikt u de opdracht az apic api definition import-specification om te importeren. Voorbeeld: 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"}'
Stap 4: Implementaties en omgevingen toevoegen
Omgevingen
Een omgeving (ontwikkeling, testen, fasering of productie) vertegenwoordigt een locatie waar een API-runtime wordt geïmplementeerd. API Platform-engineers bij Contoso definiëren twee omgevingen: testen en productie, in hun API Center-exemplaar om verschillende API-runtimes in hun organisatie te beheren en bij te houden.
Als u een omgeving wilt maken,
Selecteer Assets > Environments + New environment in > het linkermenu.
Voeg de volgende gegevens toe.
Selecteer Maken.
Herhaal dezelfde stappen voor de productieomgeving.
Voer de volgende CLI-opdracht uit om een omgeving te maken
az apic environment create -g contoso -n contoso-apis --title ContosoTesting --environment-id contosotesting --type testing
Herhaal hetzelfde voor de productieomgeving
az apic environment create -g contoso -n contoso-apis-new --title ContosoProduction --environment-id contosoproduction --type production
Notitie
Het maken van omgevingen wordt momenteel niet ondersteund in VS Code. Gebruik de Azure CLI of de Azure Portal-optie voor deze stap.
Installaties
Er wordt een unieke locatie (adres) opgegeven voor gebruikers die met uw API kunnen communiceren voor elke API-runtime in een bepaalde omgeving. Deze locatie wordt een implementatie genoemd en één API-versie kan twee implementaties hebben: een fasering en een productie-implementatie.
Contoso heeft één API, de Conferentie-API, die we koppelen aan de omgevingen die we hebben gemaakt.
Navigeer in de portal naar uw API-centrum.
Selecteer API's in het linkermenu en selecteer vervolgens een API, bijvoorbeeld de Conferentie-API.
Vouw op de pagina Conferentie-API details-implementaties > > en implementatie toevoegen uit.
Voeg de volgende informatie toe:
a. Selecteer Contoso Testen in de vervolgkeuzelijst voor het veld Omgeving .
b. Klik voor de definitie op Selecteren, kies de API-versie v1 in de vervolgkeuzelijst en selecteer de definitie die u eerder hebt toegevoegd. Klik op Selecteren.
c. Nadat de definitie is toegevoegd, voegt u een basisruntime-URL toe die specifiek is voor de API in de geselecteerde omgeving.
Als u een implementatie wilt maken en deze wilt koppelen aan de omgeving die we in de bovenstaande stap hebben gemaakt, voert u de volgende CLI-opdracht uit
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/"]}'
Notitie
Het maken van implementaties wordt momenteel niet ondersteund in VS Code. Gebruik de Azure CLI of de Azure Portal-optie voor deze stap.