Merge pull request #264880 from dlepow/patch-245

v-shils · web-flow · commit 482e7379851d · 2024-03-19T11:38:31.000-07:00
[APIC] Update import-api-management-apis.md
diff --git a/articles/api-center/import-api-management-apis.md b/articles/api-center/import-api-management-apis.md
@@ -4,7 +4,7 @@ description: Add APIs to your Azure API center inventory from your API Managemen
 author: dlepow
 ms.service: api-center
 ms.topic: how-to
-ms.date: 01/25/2024
+ms.date: 03/08/2024
 ms.author: danlep 
 ms.custom: devx-track-azurecli
 # Customer intent: As an API program manager, I want to add APIs that are managed in my Azure API Management instance to my API center.
@@ -14,14 +14,17 @@ ms.custom: devx-track-azurecli
 
 This article shows how to import (add) APIs from an Azure API Management instance to your [API center](overview.md) using the Azure CLI. Adding APIs from API Management to your API inventory helps make them discoverable and accessible to developers, API program managers, and other stakeholders in your organization.
 
-When you add an API from an API Management instance to your API center:
+This article shows two options for using the Azure CLI to add APIs to your API center from API Management:
 
-* The API's [versions](key-concepts.md#api-version), [definitions](key-concepts.md#api-definition), and [deployment](key-concepts.md#deployment) information are copied to your API center.
-* The API receives a system-generated API name in your API center. It retains its display name (title) from API Management.
-* The **Lifecycle stage** of the API is set to *Design*.
-* Azure API Management is added as an [environment](key-concepts.md#environment).
+* **Option 1** - Export an API definition from an API Management instance using the [az apim api export](/cli/azure/apim/api#az-apim-api-export) command. Then, import the definition to your API center. 
 
-After adding an API from API Management, you can add metadata and documentation in your API center to help stakeholders discover, understand, and consume the API.
+    Possible ways to import an API definition exported from API Management include:
+    * Run [az apic api register](/cli/azure/apic/api#az-apic-api-register) to register a new API in your API center.
+    * Run [az apic api definition import-specification](/cli/azure/apic/api/definition#az-apic-api-definition-import-specification) to import the API definition to an existing API.
+
+* **Option 2** - Import APIs directly from API Management to your API center using the [az apic service import-from-apim](/cli/azure/apic/service#az-apic-service-import-from-apim) command.
+    
+After importing API definitions or APIs from API Management, you can add metadata and documentation in your API center to help stakeholders discover, understand, and consume the API.
 
 > [!VIDEO https://www.youtube.com/embed/SuGkhuBUV5k]
 
@@ -31,7 +34,7 @@ After adding an API from API Management, you can add metadata and documentation
 
 * An API center in your Azure subscription. If you haven't created one, see [Quickstart: Create your API center](set-up-api-center.md).
 
-* One or more instances of Azure API Management, in the same or a different subscription in your directory. If you haven't created one, see [Create an Azure API Management instance](../api-management/get-started-create-service-instance.md).
+* One or more instances of Azure API Management, in the same or a different subscription. When you import APIs directly from API Management, the API Management instance and API center must be in the same directory. If you haven't created one, see [Create an Azure API Management instance](../api-management/get-started-create-service-instance.md).
 
 * One or more APIs managed in your API Management instance that you want to add to your API center. 
 
@@ -44,12 +47,95 @@ After adding an API from API Management, you can add metadata and documentation
     > [!NOTE]
     > Azure CLI command examples in this article can run in PowerShell or a bash shell. Where needed because of different variable syntax, separate command examples are provided for the two shells.
 
+## Option 1: Export an API definition from API Management and import it to your API center
+
+First, export an API from your API Management instance to an API definition using the [az apim api export](/cli/azure/apim/api#az-apim-api-export) command. Depending on your scenario, you can export the API definition to a local file or a URL.
+
+### Export API to a local API definition file
+
+The following example command exports the API with identifier *my-api* in the *myAPIManagement* instance of API. The API is exported in OpenApiJson format to a local OpenAPI definition file named *specificationFile.json*. 
+
+```azurecli
+#! /bin/bash
+az apim api export --api-id my-api --resource-group myResourceGroup \
+    --service-name myAPIManagement --export-format OpenApiJsonFile \
+    --file-path /path/to/folder
+```
+
+```azurecli
+#! PowerShell syntax
+az apim api export --api-id my-api --resource-group myResourceGroup `
+    --service-name myAPIManagement --export-format OpenApiJsonFile `
+    --file-path /path/to/folder
+```
+### Export API to a URL
+
+In the following example, [az apim api export](/cli/azure/apim/api#az-apim-api-export) exports the API with identifier *my-api* in OpenApiJson format to a URL in Azure storage. The URL is available for approximately 5 minutes. Here, the value of the URL is stored in the *$link* variable.
+
+
+```azurecli
+#! /bin/bash
+link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
+    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
+    --output tsv)
+```
+
+```azurecli
+# PowerShell syntax
+$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
+    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
+    --output tsv)
+```
+### Register API in your API center from exported API definition
+
+You can register a new API in your API center from the exported definition by using the [az apic api register](/cli/azure/apic/api#az-apic-api-register) command.
+
+The following example registers an API in the *myAPICenter* API center from a local OpenAPI definition file named *definitionFile.json*.
+
+```azurecli
+az apic api register --resource-group myResourceGroup --service myAPICenter --api-location "/path/to/definitionFile.json
+```
+
+### Import API definition to an existing API in your API center
+
+The following example uses the [az apic api definition import-specification](/cli/azure/apic/api/definition#az-apic-api-definition-import-specification) command to import an API definition to an existing API in the *myAPICenter* API center. Here, the API definition is imported from a URL stored in the *$link* variable.
+
+This example assumes you have an API named *my-api* and an associated API version *v1-0-0* and definition entity *openapi* in your API center. If you don't, see [Add APIs to your API center](manage-apis-azure-cli.md#register-api-api-version-and-definition).
 
-## Add a managed identity in your API center
+```azurecli
+#! /bin/bash
+az apic api definition import-specification \
+    --resource-group myResourceGroup --service myAPICenter \
+    --api-name my-api --version-name v1-0-0 \
+    --definition-name openapi --format "link" --value '$link' \
+    --specification '{"name":"openapi","version":"3.0.2"}'
+```
+
+```azurecli
+# PowerShell syntax
+az apic api definition import-specification `
+    --resource-group myResourceGroup --service myAPICenter `
+    --api-name my-api --version-name v1-0-0 `
+    --definition-name openapi --format "link" --value '$link' `
+    --specification '{"name":"openapi","version":"3.0.2"}'
+```
+
+## Option 2: Import APIs directly from your API Management instance
+
+The following are steps to import APIs from your API Management instance to your API center using the [az apic service import-from-apim](/cli/azure/apic/service#az-apic-service-import-from-apim) command. This command is useful when you want to import multiple APIs from API Management to your API center, but you can also use it to import a single API.
+
+When you add APIs from an API Management instance to your API center using `az apic service import-from-apim`, the following happens automatically:
+    
+* Each API's [versions](key-concepts.md#api-version), [definitions](key-concepts.md#api-definition), and [deployment](key-concepts.md#deployment) information are copied to your API center.
+* The API receives a system-generated API name in your API center. It retains its display name (title) from API Management.
+* The **Lifecycle stage** of the API is set to *Design*.
+* Azure API Management is added as an [environment](key-concepts.md#environment).
+
+### Add a managed identity in your API center
 
 For this scenario, your API center uses a [managed identity](/entra/identity/managed-identities-azure-resources/overview) to access APIs in your API Management instance. You can use either a system-assigned or user-assigned managed identity. If you haven't added a managed identity in your API center, you can add it in the Azure portal or by using the Azure CLI. 
 
-### Add a system-assigned identity
+#### Add a system-assigned identity
 
 #### [Portal](#tab/portal)
 
@@ -67,7 +153,7 @@ az apic service update --name <api-center-name> --resource-group <resource-group
 ```
 ---
 
-### Add a user-assigned identity
+#### Add a user-assigned identity
 
 To add a user-assigned identity, you need to create a user-assigned identity resource, and then add it to your API center.
 
@@ -115,7 +201,7 @@ To add a user-assigned identity, you need to create a user-assigned identity res
     ```
 ---
 
-## Assign the managed identity the API Management Service Reader role
+### Assign the managed identity the API Management Service Reader role
 
 To allow import of APIs, assign your API center's managed identity the **API Management Service Reader** role in your API Management instance. You can use the [portal](../role-based-access-control/role-assignments-portal-managed-identity.md) or the Azure CLI.
 
@@ -195,7 +281,7 @@ To allow import of APIs, assign your API center's managed identity the **API Man
         --scope $scope 
 ---
 
-## Import APIs from your API Management instance
+### Import APIs directly from your API Management instance
 
 Use the [az apic service import-from-apim](/cli/azure/apic/service#az-apic-service-import-from-apim) command to import one or more APIs from your API Management instance to your API center. 
 
@@ -204,7 +290,7 @@ Use the [az apic service import-from-apim](/cli/azure/apic/service#az-apic-servi
 >
 > * If your API center has multiple managed identities, the command searches first for a system-assigned identity. If none is found, it picks the first user-assigned identity in the list. 
 
-### Import all APIs from an API Management instance
+#### Import all APIs from an API Management instance
 
 Use a wildcard (`*`) to specify all APIs from the API Management instance. 
 
@@ -223,23 +309,13 @@ Use a wildcard (`*`) to specify all APIs from the API Management instance.
 1. Use the `az apic service import-from-apim` command to import the APIs. Substitute the names of your API center and resource group, and use `*` to specify all APIs from the API Management instance.
 
     ```azurecli
-    #! /bin/bash
-    apiIDs="$apimID/apis/*"
-
-    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apiIDs    
-    ```
-    
-    ```azurecli 
-    # PowerShell syntax
-    $apiIDs=$apimID + "/apis/*"
-
-    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apiIDs    
+    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/*  
     ```
 
     > [!NOTE]
     > If your API Management instance has a large number of APIs, import to your API center might take some time.
     
-### Import a specific API from an API Management instance
+#### Import a specific API from an API Management instance
 
 Specify an API to import using its name from the API Management instance. 
 
@@ -258,19 +334,9 @@ Specify an API to import using its name from the API Management instance.
 1. Use the `az apic service import-from-apim` command to import the API. Substitute the names of your API center and resource group, and specify an API name from the API Management instance.
 
     ```azurecli
-    #! /bin/bash
-    apiIDs="$apimID/apis/<api-name>"
-
-    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apiIDs    
+    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>    
     ```
     
-    ```azurecli 
-    # PowerShell syntax
-    $apiIDs=$apimID + "/apis/<api-name>"
-
-    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apiIDs    
-    ```
-
     > [!NOTE]
     > Specify `<api-name>` using the API resource name in the API Management instance, not the display name. Example: `petstore-api` instead of `Petstore API`.
     
@@ -279,6 +345,7 @@ After importing APIs from API Management, you can view and manage the imported A
 ## Related content
 
 * [Azure CLI reference for API Center](/cli/azure/apic) 
+* [Azure CLI reference for API Management](/cli/azure/apim) 
 * [Manage API inventory with Azure CLI commands](manage-apis-azure-cli.md)
 * [Assign Azure roles to a managed identity](../role-based-access-control/role-assignments-portal-managed-identity.md)
 * [Azure API Management documentation](../api-management/index.yml)
diff --git a/articles/api-center/register-apis.md b/articles/api-center/register-apis.md
@@ -120,7 +120,7 @@ To add an API definition to your version:
         | **Description** | Optionally enter a description. | Description of the API definition. |
         | **Specification name** | For the Demo Conference API, select **OpenAPI**. | Specification format for the API.|
         | **Specification version** | Enter a version identifier of your choice, such as *2.0*. | Specification version. |
-        |**Document**        | Browse to a definition file for the Demo Conference API.      |  API definition file.     |
+        |**Document**        | Browse to a definition file for the Demo Conference API, or enter a URL.      |  API definition file.     |
 
         :::image type="content" source="media/register-apis/add-definition.png" alt-text="Screenshot of adding an API definition in the portal." lightbox="media/register-apis/add-definition.png" :::
 
