AI 原生开放教材

外观

Microsoft Agent Skills技能与配置库·英文原文 ↗原件 ↓仓库 ↗

Azure API Center Management SDK Acceptance Criteria ​

SDK: azure-mgmt-apicenterRepository: https://github.com/Azure/azure-sdk-for-pythonPackage: azure.mgmt.apicenterPurpose: Skill testing acceptance criteria for validating generated code correctness

1. Correct Import Patterns ​

1.1 Client Imports ​

✅ CORRECT: ApiCenterMgmtClient ​

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

✅ CORRECT: Async Credential ​

python
from azure.mgmt.apicenter import ApiCenterMgmtClient
from azure.identity.aio import DefaultAzureCredential  # Async credential

1.2 Model Imports ​

✅ CORRECT: Service Model ​

python
from azure.mgmt.apicenter.models import Service

✅ CORRECT: API Models ​

python
from azure.mgmt.apicenter.models import (
    Api,
    ApiKind,
    LifecycleStage,
    ApiVersion,
    ApiDefinition,
    ApiSpecImportRequest,
    ApiSpecImportSourceFormat,
)

✅ CORRECT: Environment and Deployment Models ​

python
from azure.mgmt.apicenter.models import (
    Environment,
    EnvironmentKind,
    Deployment,
    DeploymentState,
)

✅ CORRECT: Metadata Models ​

python
from azure.mgmt.apicenter.models import MetadataSchema

1.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Importing from wrong module ​

python
# WRONG - Service is not in azure.mgmt.apicenter directly
from azure.mgmt.apicenter import Service

Correct approach: Import from the models submodule instead: from azure.mgmt.apicenter.models import Service

❌ INCORRECT: Using deprecated paths ​

python
# WRONG - Wrong import path
from azure.mgmt.apicenter.services import Service

Correct approach: Use models module: from azure.mgmt.apicenter.models import Service

❌ INCORRECT: Mixing subscription and resource group operations ​

python
# WRONG - list_by_subscription doesn't exist
apis = client.apis.list_by_subscription()

Correct approach: All API operations are scoped to resource group, service, and workspace. Use the list() method with all three parameters: client.apis.list(resource_group_name="my-rg", service_name="my-api-center", workspace_name="default")

2. Client Creation Patterns ​

2.1 ✅ CORRECT: Basic Client Creation ​

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

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

2.2 ✅ CORRECT: With Context Manager ​

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

with ApiCenterMgmtClient(
    credential=DefaultAzureCredential(),
    subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
) as client:
    # Use client here
    pass

2.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing subscription_id ​

python
# WRONG - subscription_id is required
client = ApiCenterMgmtClient(credential=credential)

Correct approach: Always pass subscription_id as a parameter when creating the client: client = ApiCenterMgmtClient(credential=credential, subscription_id=subscription_id)

❌ INCORRECT: Not using environment variable ​

python
# WRONG - hardcoded credentials
client = ApiCenterMgmtClient(
    credential=credential,
    subscription_id="12345678-1234-1234-1234-123456789012"
)

Correct approach: Always read sensitive values from environment variables instead of hardcoding them. Use os.environ["AZURE_SUBSCRIPTION_ID"] to retrieve the subscription ID at runtime.

3. API Center Service Management ​

3.1 ✅ CORRECT: Create API Center Service ​

python
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"}
    )
)

3.2 ✅ CORRECT: List API Centers ​

python
api_centers = client.services.list_by_subscription()

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

3.3 ✅ CORRECT: List API Centers in Resource Group ​

python
api_centers = client.services.list_by_resource_group(
    resource_group_name="my-resource-group"
)

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

3.4 ✅ CORRECT: Get Single API Center ​

python
api_center = client.services.get(
    resource_group_name="my-resource-group",
    service_name="my-api-center"
)

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

3.5 ✅ CORRECT: Update API Center ​

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

3.6 ✅ CORRECT: Delete API Center ​

python
client.services.delete(
    resource_group_name="my-resource-group",
    service_name="my-api-center"
)

3.7 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing location in Service creation ​

python
# WRONG - location is required
api_center = client.services.create_or_update(
    resource_group_name="my-rg",
    service_name="my-api-center",
    resource=Service()  # Missing location
)

Correct approach: Always specify a location (e.g., "eastus") when creating a Service resource. Location is a required field.

4. API Registration and Management ​

4.1 ✅ CORRECT: Register an API ​

python
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",
        kind=ApiKind.REST,
        lifecycle_stage=LifecycleStage.PRODUCTION,
        terms_of_service={"url": "https://example.com/terms"},
        contacts=[{"name": "API Team", "email": "api-team@example.com"}]
    )
)

4.2 ✅ CORRECT: List APIs ​

python
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})")

4.3 ✅ CORRECT: Get Single API ​

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

print(f"API: {api.title}")
print(f"Kind: {api.kind}")
print(f"Lifecycle: {api.lifecycle_stage}")

4.4 ✅ CORRECT: Update API ​

python
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 Updated",
        description="Updated description",
        kind=ApiKind.REST,
        lifecycle_stage=LifecycleStage.DEPRECATED
    )
)

4.5 ✅ CORRECT: Delete API ​

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

4.6 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing workspace_name ​

python
# WRONG - workspace_name is required
api = client.apis.create_or_update(
    resource_group_name="my-rg",
    service_name="my-api-center",
    api_name="my-api",
    resource=Api(title="My API", kind=ApiKind.REST)
)

Correct approach: All API operations require workspace_name parameter. The default workspace is typically named "default".

❌ INCORRECT: Using wrong ApiKind enum ​

python
# WRONG - ApiKind.SOAP might not exist, use REST, GraphQL, GRPC, WEBHOOK
api = client.apis.create_or_update(
    ...,
    resource=Api(kind="SOAP")  # Wrong
)

Correct approach: Use only valid ApiKind enum values: REST, GraphQL, GRPC, or WEBHOOK. Avoid string literals; use the enum type.

5. API Version Management ​

5.1 ✅ CORRECT: Create API Version ​

python
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
    )
)

5.2 ✅ CORRECT: List API Versions ​

python
versions = client.api_versions.list(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api"
)

for version in versions:
    print(f"{version.title} - {version.lifecycle_stage}")

5.3 ✅ CORRECT: Get API Version ​

python
version = client.api_versions.get(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1"
)

5.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing version_name ​

python
# WRONG
version = client.api_versions.create_or_update(
    resource_group_name="my-rg",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    resource=ApiVersion(title="v1")
)

Correct approach: version_name is a required parameter passed separately, not inside the resource body. Pass it as: version_name="v1" alongside the resource.

6. API Definition Management ​

6.1 ✅ CORRECT: Create API Definition ​

python
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"
    )
)

6.2 ✅ CORRECT: List API Definitions ​

python
definitions = client.api_definitions.list(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1"
)

for definition in definitions:
    print(f"{definition.title}")

6.3 ✅ CORRECT: Import API Specification (Inline) ​

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

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": {}}'
    )
)

6.4 ✅ CORRECT: Import API Specification (URL) ​

python
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.OPENAPI_3_0,
        value="https://example.com/openapi.json"
    )
)

6.5 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing definition_name ​

python
# WRONG
definition = client.api_definitions.create_or_update(
    resource_group_name="my-rg",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1",
    resource=ApiDefinition(title="OpenAPI")
)

Correct approach: definition_name is a required parameter passed separately to the method call, not inside the resource body. Use: definition_name="openapi" alongside the resource.

7. Environment Management ​

7.1 ✅ CORRECT: Create Environment ​

python
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"]
        }
    )
)

7.2 ✅ CORRECT: List Environments ​

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

for env in environments:
    print(f"{env.title} - {env.kind}")

7.3 ✅ CORRECT: Get Environment ​

python
environment = client.environments.get(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    environment_name="production"
)

7.4 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing kind ​

python
# WRONG - kind is required
environment = client.environments.create_or_update(
    ...,
    resource=Environment(
        title="Production",
        description="Prod env"
    )
)

Correct approach: Always specify the kind field (e.g., EnvironmentKind.PRODUCTION, EnvironmentKind.STAGING, etc.) when creating an Environment resource.

8. Deployment Tracking ​

8.1 ✅ CORRECT: Create Deployment ​

python
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"]}
    )
)

8.2 ✅ CORRECT: List Deployments ​

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

for deployment in deployments:
    print(f"{deployment.title} - {deployment.state}")

8.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Missing state ​

python
# WRONG - state is required for tracking
deployment = client.deployments.create_or_update(
    ...,
    resource=Deployment(
        title="Prod",
        environment_id="...",
        definition_id="..."
    )
)

Correct approach: Always specify the state field (e.g., DeploymentState.ACTIVE, DeploymentState.INACTIVE) when creating a Deployment resource for proper lifecycle tracking.

9. Custom Metadata Management ​

9.1 ✅ CORRECT: Define Custom Metadata Schema ​

python
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"]}'
    )
)

9.2 ✅ CORRECT: List Metadata Schemas ​

python
schemas = client.metadata_schemas.list(
    resource_group_name="my-resource-group",
    service_name="my-api-center"
)

for schema in schemas:
    print(f"{schema.name}")

9.3 Anti-Patterns (ERRORS) ​

❌ INCORRECT: Invalid JSON schema ​

python
# WRONG - schema must be valid JSON
metadata = client.metadata_schemas.create_or_update(
    ...,
    resource=MetadataSchema(
        schema='invalid json'
    )
)

Correct approach: Always pass valid JSON for the schema field. The schema should be a properly formatted JSON string that defines the structure and constraints for the metadata.

10. Best Practices ​

✅ Pattern: Complete API Center Workflow ​

python
import os
from azure.mgmt.apicenter import ApiCenterMgmtClient
from azure.mgmt.apicenter.models import (
    Service,
    Api,
    ApiKind,
    LifecycleStage,
    ApiVersion,
    ApiDefinition,
    Environment,
    EnvironmentKind,
    Deployment,
    DeploymentState,
    ApiSpecImportRequest,
    ApiSpecImportSourceFormat,
)
from azure.identity import DefaultAzureCredential

def main():
    # Create client
    client = ApiCenterMgmtClient(
        credential=DefaultAzureCredential(),
        subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
    )
    
    # Create API Center
    api_center = client.services.create_or_update(
        resource_group_name="my-rg",
        service_name="my-api-center",
        resource=Service(location="eastus")
    )
    
    # Register API
    api = client.apis.create_or_update(
        resource_group_name="my-rg",
        service_name="my-api-center",
        workspace_name="default",
        api_name="my-api",
        resource=Api(
            title="My API",
            kind=ApiKind.REST,
            lifecycle_stage=LifecycleStage.PRODUCTION
        )
    )
    
    # Create API Version
    version = client.api_versions.create_or_update(
        resource_group_name="my-rg",
        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
        )
    )
    
    # Add API Definition
    definition = client.api_definitions.create_or_update(
        resource_group_name="my-rg",
        service_name="my-api-center",
        workspace_name="default",
        api_name="my-api",
        version_name="v1",
        definition_name="openapi",
        resource=ApiDefinition(title="OpenAPI Definition")
    )
    
    # Create Environment
    environment = client.environments.create_or_update(
        resource_group_name="my-rg",
        service_name="my-api-center",
        workspace_name="default",
        environment_name="production",
        resource=Environment(
            title="Production",
            kind=EnvironmentKind.PRODUCTION
        )
    )
    
    # Create Deployment
    deployment = client.deployments.create_or_update(
        resource_group_name="my-rg",
        service_name="my-api-center",
        workspace_name="default",
        api_name="my-api",
        deployment_name="prod-deployment",
        resource=Deployment(
            title="Production Deployment",
            state=DeploymentState.ACTIVE,
            environment_id=environment.id,
            definition_id=definition.id
        )
    )
    
    print(f"Created API Center: {api_center.name}")
    print(f"Registered API: {api.title}")
    print(f"Deployment state: {deployment.state}")

if __name__ == "__main__":
    main()

11. Environment Variables ​

Required Variables ​

bash
AZURE_SUBSCRIPTION_ID=your-subscription-id

12. Common Errors and Fixes ​

ErrorCauseFix
TypeError: __init__() missing required argument 'subscription_id'Missing subscription_idAdd subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
AttributeError: 'ApiCenterMgmtClient' has no attribute 'apis'Client not properly initializedEnsure using context manager or explicit close
ValueError: resource_group_name cannot be NoneMissing parameterAll operations require resource_group_name
AttributeError: 'ApiKind' has no attribute 'SOAP'Wrong ApiKind valueUse REST, GraphQL, GRPC, or WEBHOOK
TypeError: Api() missing required argument 'title'Missing required model fieldAll models require title field
ValueError: workspace_name cannot be NoneMissing workspace_nameAPIs require workspace_name parameter

13. Test Scenarios Checklist ​

API Center Service Management ​

  • [ ] Create API Center with location
  • [ ] List API Centers by subscription
  • [ ] List API Centers by resource group
  • [ ] Get single API Center
  • [ ] Update API Center tags
  • [ ] Delete API Center

API Registration ​

  • [ ] Register REST API
  • [ ] Register GraphQL API
  • [ ] Register GRPC API
  • [ ] List APIs in workspace
  • [ ] Get single API
  • [ ] Update API lifecycle stage
  • [ ] Delete API

API Versions ​

  • [ ] Create API version
  • [ ] List API versions
  • [ ] Get single version
  • [ ] Update version lifecycle
  • [ ] Delete version

API Definitions ​

  • [ ] Create API definition
  • [ ] List definitions
  • [ ] Import OpenAPI spec (inline)
  • [ ] Import OpenAPI spec (URL)
  • [ ] Delete definition

Environments ​

  • [ ] Create production environment
  • [ ] Create staging environment
  • [ ] List environments
  • [ ] Get environment
  • [ ] Delete environment

Deployments ​

  • [ ] Create deployment in active state
  • [ ] List deployments
  • [ ] Get deployment
  • [ ] Update deployment state
  • [ ] Delete deployment

Metadata ​

  • [ ] Create string metadata schema
  • [ ] Create enum metadata schema
  • [ ] List metadata schemas
  • [ ] Delete schema

Governance ​

  • [ ] Use workspaces to organize APIs
  • [ ] Track API lifecycle stages
  • [ ] Manage API contacts
  • [ ] Define terms of service
  • [ ] Track deployment locations