azure-mgmt-apicenter-py

用途

Azure API Center Management SDK for Python（azure-mgmt-apicenter）用于在 Azure API Center 中管理 API 清单、元数据与治理。它面向需要在组织范围内集中登记、组织和跟踪 API 的开发者与平台团队。

主要能力

该 SDK 提供 ApiCenterMgmtClient 主客户端，并包含以下操作组：

services：API Center 服务管理
workspaces：工作区管理
apis：API 注册与管理
api_versions：API 版本管理
api_definitions：API 定义管理
deployments：部署跟踪
environments：环境管理
metadata_schemas：自定义元数据定义

具体可执行的操作包括：创建与列出 API Center、注册 API、创建 API 版本、添加 API 定义、导入 API 规范、列出 API、创建环境、创建部署、定义自定义元数据。

安装

pip install azure-mgmt-apicenter
pip install azure-identity

环境变量

AZURE_SUBSCRIPTION_ID=your-subscription-id

认证

from azure.identity import DefaultAzureCredential
from azure.mgmt.apicenter import ApiCenterMgmtClient
import os

client = ApiCenterMgmtClient(
    credential=DefaultAzureCredential(),
    subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
)

使用方式

创建 API Center

from azure.mgmt.apicenter.models import Service

api_center = client.services.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    resource=Service(
        location="eastus",
        tags={"environment": "production"}
    )
)

print(f"Created API Center: {api_center.name}")

列出 API Center

api_centers = client.services.list_by_subscription()

for api_center in api_centers:
    print(f"{api_center.name} - {api_center.location}")

注册 API

from azure.mgmt.apicenter.models import Api, ApiKind, LifecycleStage

api = client.apis.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    resource=Api(
        title="My API",
        description="A sample API for demonstration",
        kind=ApiKind.REST,
        lifecycle_stage=LifecycleStage.PRODUCTION,
        terms_of_service={"url": "https://example.com/terms"},
        contacts=[{"name": "API Team", "email": "api-team@example.com"}]
    )
)

print(f"Registered API: {api.title}")

创建 API 版本

from azure.mgmt.apicenter.models import ApiVersion, LifecycleStage

version = client.api_versions.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1",
    resource=ApiVersion(
        title="Version 1.0",
        lifecycle_stage=LifecycleStage.PRODUCTION
    )
)

print(f"Created version: {version.title}")

添加 API 定义

from azure.mgmt.apicenter.models import ApiDefinition

definition = client.api_definitions.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1",
    definition_name="openapi",
    resource=ApiDefinition(
        title="OpenAPI Definition",
        description="OpenAPI 3.0 specification"
    )
)

导入 API 规范

from azure.mgmt.apicenter.models import ApiSpecImportRequest, ApiSpecImportSourceFormat

# Import from inline content
client.api_definitions.import_specification(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1",
    definition_name="openapi",
    body=ApiSpecImportRequest(
        format=ApiSpecImportSourceFormat.INLINE,
        value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {}}'
    )
)

列出 API

apis = client.apis.list(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default"
)

for api in apis:
    print(f"{api.name}: {api.title} ({api.kind})")

创建环境

from azure.mgmt.apicenter.models import Environment, EnvironmentKind

environment = client.environments.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    environment_name="production",
    resource=Environment(
        title="Production",
        description="Production environment",
        kind=EnvironmentKind.PRODUCTION,
        server={"type": "Azure API Management", "management_portal_uri": ["https://portal.azure.com"]}
    )
)

创建部署

from azure.mgmt.apicenter.models import Deployment, DeploymentState

deployment = client.deployments.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    deployment_name="prod-deployment",
    resource=Deployment(
        title="Production Deployment",
        description="Deployed to production APIM",
        environment_id="/workspaces/default/environments/production",
        definition_id="/workspaces/default/apis/my-api/versions/v1/definitions/openapi",
        state=DeploymentState.ACTIVE,
        server={"runtime_uri": ["https://api.example.com"]}
    )
)

定义自定义元数据

from azure.mgmt.apicenter.models import MetadataSchema

metadata = client.metadata_schemas.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    metadata_schema_name="data-classification",
    resource=MetadataSchema(
        schema='{"type": "string", "title": "Data Classification", "enum": ["public", "internal", "confidential"]}'
    )
)

客户端与操作组

客户端：

Client	Purpose
ApiCenterMgmtClient	Main client for all operations

操作组：

Operation Group	Purpose
services	API Center service management
workspaces	Workspace management
apis	API registration and management
api_versions	API version management
api_definitions	API definition management
deployments	Deployment tracking
environments	Environment management
metadata_schemas	Custom metadata definitions

最佳实践

使用工作区按团队或领域组织 API
定义元数据架构以实现一致的治理
跟踪部署以了解 API 的运行位置
导入规范以支持 API 分析与 linting
使用生命周期阶段跟踪 API 成熟度
添加联系人以便 API 归属与支持

适用场景

该技能适用于执行概述中描述的工作流或操作，即通过 Python 在 Azure API Center 中管理 API 清单、元数据与治理。

限制

仅当任务明确匹配上述范围时使用此技能。
不要将输出视为环境特定验证、测试或专家审查的替代品。
如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。