azure-mgmt-apimanagement-py
用 Python 管理 APIM 服務、API、product、subscription 和 policy
中文翻譯
---
name: azure-mgmt-apimanagement-py
description: |
Azure API Management SDK for Python。用於管理 APIM 服務、API、product、subscription 和 policy。
Triggers: "azure-mgmt-apimanagement", "ApiManagementClient", "APIM", "API gateway", "API Management".
license: MIT
metadata:
author: Microsoft
version: "1.0.0"
package: azure-mgmt-apimanagement
---
# Azure API Management SDK for Python
管理 Azure API Management 服務、API、product 和 policy。
## 安裝
```bash
pip install azure-mgmt-apimanagement
pip install azure-identity
```
## 環境變數
```bash
AZURE_SUBSCRIPTION_ID=your-subscription-id # 所有認證方式都必填
AZURE_TOKEN_CREDENTIALS=prod # 只有在正式環境用 DefaultAzureCredential 時才需要
```
## 認證與生命週期
> **🔑 底下每個程式碼範例都適用兩條規則：**
>
> 1. **優先用 `DefaultAzureCredential`。** 它在本機（Azure CLI / VS Code / Developer CLI）和 Azure 上（managed identity、workload identity）都能運作，程式碼不用改。避免用連線字串、帳號/API key，它們會繞過 Entra 的稽核和輪替。
> - 本機開發：`DefaultAzureCredential` 直接可用。
> - 正式環境：設 `AZURE_TOKEN_CREDENTIALS=prod`（或 `AZURE_TOKEN_CREDENTIALS=<specific_credential>`），把 credential 鏈限制在適合正式環境的 credential。
> 2. **每個 client 都要包在 context manager 裡**，這樣 HTTP transport、socket 和 token cache 才會確實釋放：
> - 同步：`with <Client>(...) as client:`
> - 非同步：`async with <Client>(...) as client:` **而且**要 `async with DefaultAzureCredential() as credential:`（來自 `azure.identity.aio`）
>
> 範例片段可能會簡化這段設定，但正式環境的程式碼一定要遵守這兩條規則。
```python
from azure.identity import DefaultAzureCredential
from azure.mgmt.apimanagement import ApiManagementClient
import os
with ApiManagementClient(
credential=DefaultAzureCredential(),
subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
) as client:
# 後續所有操作都用 `client`（見下面的範例）
...
```
## 建立 APIM 服務
```python
from azure.mgmt.apimanagement.models import (
ApiManagementServiceResource,
ApiManagementServiceSkuProperties,
SkuType
)
service = client.api_management_service.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
parameters=ApiManagementServiceResource(
location="eastus",
publisher_email="admin@example.com",
publisher_name="My Organization",
sku=ApiManagementServiceSkuProperties(
name=SkuType.DEVELOPER,
capacity=1
)
)
).result()
print(f"Created APIM: {service.name}")
```
## 從 OpenAPI 匯入 API
```python
from azure.mgmt.apimanagement.models import (
ApiCreateOrUpdateParameter,
ContentFormat,
Protocol
)
api = client.api.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
api_id="my-api",
parameters=ApiCreateOrUpdateParameter(
display_name="My API",
path="myapi",
protocols=[Protocol.HTTPS],
format=ContentFormat.OPENAPI_JSON,
value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {"/health": {"get": {"responses": {"200": {"description": "OK"}}}}}}'
)
).result()
print(f"Imported API: {api.display_name}")
```
## 從 URL 匯入 API
```python
api = client.api.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
api_id="petstore",
parameters=ApiCreateOrUpdateParameter(
display_name="Petstore API",
path="petstore",
protocols=[Protocol.HTTPS],
format=ContentFormat.OPENAPI_LINK,
value="https://petstore.swagger.io/v2/swagger.json"
)
).result()
```
## 列出 API
```python
apis = client.api.list_by_service(
resource_group_name="my-resource-group",
service_name="my-apim"
)
for api in apis:
print(f"{api.name}: {api.display_name} - {api.path}")
```
## 建立 Product
```python
from azure.mgmt.apimanagement.models import ProductContract
product = client.product.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
product_id="premium",
parameters=ProductContract(
display_name="Premium",
description="Premium tier with unlimited access",
subscription_required=True,
approval_required=False,
state="published"
)
)
print(f"Created product: {product.display_name}")
```
## 把 API 加進 Product
```python
client.product_api.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
product_id="premium",
api_id="my-api"
)
```
## 建立 Subscription
```python
from azure.mgmt.apimanagement.models import SubscriptionCreateParameters
subscription = client.subscription.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
sid="my-subscription",
parameters=SubscriptionCreateParameters(
display_name="My Subscription",
scope=f"/products/premium",
state="active"
)
)
print(f"Subscription key: {subscription.primary_key}")
```
## 設定 API Policy
```python
from azure.mgmt.apimanagement.models import PolicyContract
policy_xml = """
<policies>
<inbound>
<rate-limit calls="100" renewal-period="60" />
<set-header name="X-Custom-Header" exists-action="override">
<value>CustomValue</value>
</set-header>
</inbound>
<backend>
<forward-request />
</backend>
<outbound />
<on-error />
</policies>
"""
client.api_policy.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
api_id="my-api",
policy_id="policy",
parameters=PolicyContract(
value=policy_xml,
format="xml"
)
)
```
## 建立 Named Value（機密）
```python
from azure.mgmt.apimanagement.models import NamedValueCreateContract
named_value = client.named_value.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
named_value_id="backend-api-key",
parameters=NamedValueCreateContract(
display_name="Backend API Key",
value="secret-key-value",
secret=True
)
).result()
```
## 建立 Backend
```python
from azure.mgmt.apimanagement.models import BackendContract
backend = client.backend.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
backend_id="my-backend",
parameters=BackendContract(
url="https://api.backend.example.com",
protocol="http",
description="My backend service"
)
)
```
## 建立使用者
```python
from azure.mgmt.apimanagement.models import UserCreateParameters
user = client.user.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
user_id="newuser",
parameters=UserCreateParameters(
email="user@example.com",
first_name="John",
last_name="Doe"
)
)
```
## Operation Group
| Group | 用途 |
|-------|---------|
| `api_management_service` | APIM 執行個體管理 |
| `api` | API 操作 |
| `api_operation` | API operation 細節 |
| `api_policy` | API 層級的 policy |
| `product` | Product 管理 |
| `product_api` | Product 與 API 的關聯 |
| `subscription` | Subscription 管理 |
| `user` | 使用者管理 |
| `named_value` | Named value/機密 |
| `backend` | Backend 服務 |
| `certificate` | 憑證 |
| `gateway` | 自行代管的 gateway |
## 最佳實務
1. **同步或非同步擇一，並保持一致。** 同一條呼叫路徑裡，不要混用 `azure.xxx` 同步 client 和 `azure.xxx.aio` 非同步 client。每個 module 選一種模式。
2. **client 和非同步 credential 一律用 context manager。** 每個 client 都包在 `with Client(...) as client:`（同步）或 `async with Client(...) as client:`（非同步）裡。非同步的 `DefaultAzureCredential`（來自 `azure.identity.aio`）也要用 `async with credential:`，這樣 token 和 transport 才會清理乾淨。
3. 機密和設定用 **named value**
4. 在合適的範圍套用 **policy**（全域、product、API、operation）
5. 用 **product** 打包 API 並管理存取
6. 啟用 **Application Insights** 做監控
7. 用 **backend** 抽象化後端服務
8. 用 APIM 的版本控制功能替 **API 做版本管理**
## 參考檔案
| 檔案 | 內容 |
|------|----------|
| [references/capabilities.md](references/capabilities.md) | 其他非主打的功能、operation group 涵蓋範圍，以及正式環境檢查清單。 |
| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | 次要/進階情境的專屬非主打範例。 |英文原文
---
name: azure-mgmt-apimanagement-py
description: |
Azure API Management SDK for Python. Use for managing APIM services, APIs, products, subscriptions, and policies.
Triggers: "azure-mgmt-apimanagement", "ApiManagementClient", "APIM", "API gateway", "API Management".
license: MIT
metadata:
author: Microsoft
version: "1.0.0"
package: azure-mgmt-apimanagement
---
# Azure API Management SDK for Python
Manage Azure API Management services, APIs, products, and policies.
## Installation
```bash
pip install azure-mgmt-apimanagement
pip install azure-identity
```
## Environment Variables
```bash
AZURE_SUBSCRIPTION_ID=your-subscription-id # Required for all auth methods
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
```
## Authentication & Lifecycle
> **🔑 Two rules apply to every code sample below:**
>
> 1. **Prefer `DefaultAzureCredential`.** It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
> - Local dev: `DefaultAzureCredential` works as-is.
> - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=<specific_credential>`) to constrain the credential chain to production-safe credentials.
> 2. **Wrap every client in a context manager** so HTTP transports, sockets, and token caches are released deterministically:
> - Sync: `with <Client>(...) as client:`
> - Async: `async with <Client>(...) as client:` **and** `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`)
>
> Snippets may abbreviate this setup, but production code should always follow both rules.
```python
from azure.identity import DefaultAzureCredential
from azure.mgmt.apimanagement import ApiManagementClient
import os
with ApiManagementClient(
credential=DefaultAzureCredential(),
subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
) as client:
# Use `client` for all subsequent operations (see examples below)
...
```
## Create APIM Service
```python
from azure.mgmt.apimanagement.models import (
ApiManagementServiceResource,
ApiManagementServiceSkuProperties,
SkuType
)
service = client.api_management_service.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
parameters=ApiManagementServiceResource(
location="eastus",
publisher_email="admin@example.com",
publisher_name="My Organization",
sku=ApiManagementServiceSkuProperties(
name=SkuType.DEVELOPER,
capacity=1
)
)
).result()
print(f"Created APIM: {service.name}")
```
## Import API from OpenAPI
```python
from azure.mgmt.apimanagement.models import (
ApiCreateOrUpdateParameter,
ContentFormat,
Protocol
)
api = client.api.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
api_id="my-api",
parameters=ApiCreateOrUpdateParameter(
display_name="My API",
path="myapi",
protocols=[Protocol.HTTPS],
format=ContentFormat.OPENAPI_JSON,
value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {"/health": {"get": {"responses": {"200": {"description": "OK"}}}}}}'
)
).result()
print(f"Imported API: {api.display_name}")
```
## Import API from URL
```python
api = client.api.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
api_id="petstore",
parameters=ApiCreateOrUpdateParameter(
display_name="Petstore API",
path="petstore",
protocols=[Protocol.HTTPS],
format=ContentFormat.OPENAPI_LINK,
value="https://petstore.swagger.io/v2/swagger.json"
)
).result()
```
## List APIs
```python
apis = client.api.list_by_service(
resource_group_name="my-resource-group",
service_name="my-apim"
)
for api in apis:
print(f"{api.name}: {api.display_name} - {api.path}")
```
## Create Product
```python
from azure.mgmt.apimanagement.models import ProductContract
product = client.product.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
product_id="premium",
parameters=ProductContract(
display_name="Premium",
description="Premium tier with unlimited access",
subscription_required=True,
approval_required=False,
state="published"
)
)
print(f"Created product: {product.display_name}")
```
## Add API to Product
```python
client.product_api.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
product_id="premium",
api_id="my-api"
)
```
## Create Subscription
```python
from azure.mgmt.apimanagement.models import SubscriptionCreateParameters
subscription = client.subscription.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
sid="my-subscription",
parameters=SubscriptionCreateParameters(
display_name="My Subscription",
scope=f"/products/premium",
state="active"
)
)
print(f"Subscription key: {subscription.primary_key}")
```
## Set API Policy
```python
from azure.mgmt.apimanagement.models import PolicyContract
policy_xml = """
<policies>
<inbound>
<rate-limit calls="100" renewal-period="60" />
<set-header name="X-Custom-Header" exists-action="override">
<value>CustomValue</value>
</set-header>
</inbound>
<backend>
<forward-request />
</backend>
<outbound />
<on-error />
</policies>
"""
client.api_policy.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
api_id="my-api",
policy_id="policy",
parameters=PolicyContract(
value=policy_xml,
format="xml"
)
)
```
## Create Named Value (Secret)
```python
from azure.mgmt.apimanagement.models import NamedValueCreateContract
named_value = client.named_value.begin_create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
named_value_id="backend-api-key",
parameters=NamedValueCreateContract(
display_name="Backend API Key",
value="secret-key-value",
secret=True
)
).result()
```
## Create Backend
```python
from azure.mgmt.apimanagement.models import BackendContract
backend = client.backend.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
backend_id="my-backend",
parameters=BackendContract(
url="https://api.backend.example.com",
protocol="http",
description="My backend service"
)
)
```
## Create User
```python
from azure.mgmt.apimanagement.models import UserCreateParameters
user = client.user.create_or_update(
resource_group_name="my-resource-group",
service_name="my-apim",
user_id="newuser",
parameters=UserCreateParameters(
email="user@example.com",
first_name="John",
last_name="Doe"
)
)
```
## Operation Groups
| Group | Purpose |
|-------|---------|
| `api_management_service` | APIM instance management |
| `api` | API operations |
| `api_operation` | API operation details |
| `api_policy` | API-level policies |
| `product` | Product management |
| `product_api` | Product-API associations |
| `subscription` | Subscription management |
| `user` | User management |
| `named_value` | Named values/secrets |
| `backend` | Backend services |
| `certificate` | Certificates |
| `gateway` | Self-hosted gateways |
## Best Practices
1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module.
2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up.
3. **Use named values** for secrets and configuration
4. **Apply policies** at appropriate scopes (global, product, API, operation)
5. **Use products** to bundle APIs and manage access
6. **Enable Application Insights** for monitoring
7. **Use backends** to abstract backend services
8. **Version your APIs** using APIM's versioning features
## Reference Files
| File | Contents |
|------|----------|
| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. |
| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. |