Skip to content

Commit eeef8eb

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #261735 from dlepow/apiccli
[APIC] Azure CLI how-to
2 parents 6fd670c + b9cffde commit eeef8eb

File tree

4 files changed

+155
-2
lines changed

4 files changed

+155
-2
lines changed

‎articles/api-center/TOC.yml

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,10 @@
2424
href: register-apis.md
2525
- name: 3 - Add environments and deployments
2626
href: configure-environments-deployments.md
27-
#- name: API inventory
27+
- name: API inventory
28+
items:
29+
- name: Manage inventory - Azure CLI
30+
href: manage-apis-azure-cli.md
2831
#- name: API governance
2932
#- name: API discovery and consumption
3033
- name: Reference
@@ -38,4 +41,6 @@
3841
- name: Java
3942
href: /java/api/overview/azure/apicenter
4043
- name: Python
41-
href: https://pypi.org/project/azure-mgmt-apicenter
44+
href: https://pypi.org/project/azure-mgmt-apicenter
45+
- name: Resource Manager template
46+
href: /azure/templates/microsoft.apicenter/allversions

‎articles/api-center/index.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,7 @@ landingContent:
4242
url: register-apis.md
4343
- text: 3 - Add environments and deployments
4444
url: configure-environments-deployments.md
45+
- linkListType: how-to-guide
46+
links:
47+
- text: Manage inventory - Azure CLI
48+
url: manage-apis-azure-cli.md

‎articles/api-center/key-concepts.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ Each API version should ideally be defined by at least one definition, such as a
4343

4444
An environment represents a location where an API runtime could be deployed, for example, an Azure API Management service, an Apigee API Management service, or a compute service such as a Kubernetes cluster, a Web App, or an Azure Function. Each environment has a type (such as production or staging) and may include information about developer portal or management interfaces.
4545

46+
> [!NOTE]
47+
> Use API Center to track any of your API runtime environments, whether or not they're hosted on Azure infrastructure. These environments aren't the same as Azure Deployment Environments.
48+
4649
## Deployment
4750

4851
A deployment is a location (an address) where users can access an API. An API can have multiple deployments, such as different staging environments or regions. For example, an API could have one deployment in an internal staging environment and a second in a production environment. Each deployment is associated with a specific API definition.

‎articles/api-center/manage-apis-azure-cli.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: Manage API inventory in Azure API Center - Azure CLI
3+
description: Use the Azure CLI to create and update APIs, API versions, and API definitions in your Azure API center.
4+
author: dlepow
5+
ms.service: api-center
6+
ms.topic: how-to
7+
ms.date: 01/12/2024
8+
ms.author: danlep
9+
ms.custom:
10+
# Customer intent: As an API program manager, I want to automate processes to register and update APIs in my Azure API center.
11+
---
12+
13+
# Use the Azure CLI to manage your API inventory
14+
15+
This article shows how to use [`az apic api`](/cli/azure/apic/api) commands in the Azure CLI to add and configure APIs in your [API center](overview.md) inventory. Use commands in the Azure CLI to script operations to manage your API inventory and other aspects of your API center.
16+
17+
[!INCLUDE [api-center-preview-feedback](includes/api-center-preview-feedback.md)]
18+
19+
## Prerequisites
20+
21+
* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
22+
23+
* For Azure CLI:
24+
[!INCLUDE [include](~/articles/reusable-content/azure-cli/azure-cli-prepare-your-environment-no-header.md)]
25+
26+
> [!NOTE]
27+
> `az apic` commands require the `apic-extension` Azure CLI extension. If you haven't used `az apic` commands, the extension is installed dynamically when you run your first `az apic` command. Learn more about [Azure CLI extensions](/cli/azure/azure-cli-extensions-overview).
28+
29+
## Register API, API version, and definition
30+
31+
The following steps show how to create an API and associate a single API version and API definition. For background about the data model in API Center, see [Key concepts](key-concepts.md).
32+
33+
### Create an API
34+
35+
Use the [az apic api create](/cli/azure/apic/api#az_apic_api_create) command to create an API in your API center.
36+
37+
The following example creates an API named *Petstore API* in the *myResourceGroup* resource group and *myAPICenter* API center. The API is a REST API.
38+
39+
```azurecli-interactive
40+
az apic api create --resource-group myResourceGroup \
41+
--service myAPICenter --name petstore-api \
42+
--title "Petstore API" --kind "rest"
43+
```
44+
45+
By default, the command sets the API's **Lifecycle stage** to *design*.
46+
47+
> [!NOTE]
48+
> After creating an API, you can update the API's properties by using the [az apic api update](/cli/azure/apic/api#az_apic_api_update) command.
49+
50+
51+
### Create an API version
52+
53+
Use the [az apic api version create](/cli/azure/apic/api/version#az_apic_api_version_create) command to create a version for your API.
54+
55+
The following example creates an API version named *v1-0-0* for the *petstore-api* API that you created in the previous section.
56+
57+
```azurecli-interactive
58+
az apic api version create --resource-group myResourceGroup \
59+
--service myAPICenter --api-name petstore-api \
60+
--version v1-0-0 --title "v1-0-0"
61+
```
62+
63+
### Create API definition and add specification file
64+
65+
Use the [az apic api definition](/cli/azure/apic/api/definition) commands to add a definition and an accompanying specification file for an API version.
66+
67+
#### Create a definition
68+
69+
The following example uses the [az apic api definition create](/cli/azure/apic/api/definition#az_apic_api_definition_create) command to create a definition named *openapi* for the *petstore-api* API version that you created in the previous section.
70+
71+
```azurecli-interactive
72+
az apic api definition create --resource-group myResourceGroup \
73+
--service myAPICenter --api-name petstore-api \
74+
--version v1-0-0 --name "openapi" --title "OpenAPI"
75+
```
76+
77+
#### Import a specification file
78+
79+
Import a specification file to the definition using the [az apic api definition import-specification](/cli/azure/apic/api/definition#az_apic_api_definition_import_specification) command.
80+
81+
The following example imports an OpenAPI specification file from a publicly accessible URL to the *openapi* definition that you created in the previous step. The `name` and `version` properties of the specification resource are passed as JSON.
82+
83+
84+
```azurecli-interactive
85+
az apic api definition import-specification \
86+
--resource-group myResourceGroup --service myAPICenter \
87+
--api-name petstore-api --version-name v1-0-0 \
88+
--definition-name openapi --format "link" \
89+
--value 'https://petstore3.swagger.io/api/v3/openapi.json' \
90+
--specification '{"name":"openapi","version":"3.0.2"}'
91+
```
92+
93+
> [!TIP]
94+
> You can import the specification file inline by setting the `--format` parameter to `inline` and passing the file contents using the `--value` parameter.
95+
96+
### Export a specification file
97+
98+
To export an API specification from your API center to a local file, use the [az apic api definition export-specification](/cli/azure/apic/api/definition#az_apic_api_definition_export_specification) command.
99+
100+
The following example exports the specification file from the *openapi* definition that you created in the previous section to a local file named *specificationFile.json*.
101+
102+
```azurecli-interactive
103+
az apic api definition export-specification \
104+
--resource-group myResourceGroup --service myAPICenter \
105+
--api-name petstore-api --version-name v1-0-0 \
106+
--definition-name openapi --file-name "/Path/to/specificationFile.json"
107+
```
108+
109+
## Register API from a specification file - single step
110+
111+
You can register an API from a local specification file in a single step by using the [az apic api register](/cli/azure/apic/api#az-apic-api-register) command. With this option, a default API version and definition are created automatically for the API.
112+
113+
The following example registers an API in the *myAPICenter* API center from a local OpenAPI definition file named *specificationFile.json*.
114+
115+
116+
```azurecli-interactive
117+
az apic api register --resource-group myResourceGroup \
118+
--service myAPICenter --api-location "/Path/to/specificationFile.json"
119+
```
120+
121+
* The command sets the API properties such as name and type from values in the definition file.
122+
* By default, the command sets the API's **Lifecycle stage** to *design*.
123+
* It creates a default API version named *1-0-0* and a default definition named according to the specification format (for example, *openapi*).
124+
125+
After registering an API, you can update the API's properties by using the [az apic api update](/cli/azure/apic/api#az_apic_api_update), [az apic api version update](/cli/azure/apic/api/version#az_apic_api_version_update), and [az apic api definition update](/cli/azure/apic/api/definition#az_apic_api_definition_update) commands.
126+
127+
## Delete API resources
128+
129+
Use the [az apic api delete](/cli/azure/apic/api#az_apic_api_delete) command to delete an API and all of its version and definition resources. For example:
130+
131+
```azurecli-interactive
132+
az apic api delete \
133+
--resource-group myResoureGroup --service myAPICenter \
134+
--name petstore-api
135+
```
136+
137+
To delete individual API versions and definitions, use [az apic api version delete](/cli/azure/apic/api/version#az-apic-api-version-delete) and [az apic api definition delete](/cli/azure/apic/api/definition#az-apic-api-definition-delete), respectively.
138+
139+
## Related content
140+
141+
See the [Azure CLI reference for API Center](/cli/azure/apic) for a complete command list, including commands to manage [environments](/cli/azure/apic/environment), [deployments](/cli/azure/apic/api/deployment), [metadata schemas](/cli/azure/apic/metadata-schema), and [API Center services](/cli/azure/apic/service).

0 commit comments

Comments
 (0)