azure-mgmt-apimanagement-dotnet

同梱されている上流ファイル

補助ファイルはスキルからの相対パスに含まれています。固定された参照元、ライセンス、ハッシュ、インポート時の変更については、UPSTREAM-NOTICE.md をご覧ください。

補助資料の利用可否

このカタログのコピーでは、以下のパスを利用できません。

• <support-root>/references/policies.md

これらのファイルを必要とする手順は実行しないでください。使用する前に、元の資料を入手し、その依存関係、ライセンス、影響を確認してください。独立したインライン手順と同梱のヘルパーは、ユーザーが許可した範囲内で実行できます。

Azure.ResourceManager.ApiManagement (.NET)

Azure Resource Manager を介して Azure API Management リソースをプロビジョニングおよび管理するための管理プレーン SDK です。

⚠️ 管理プレーンとデータプレーン

• この SDK（Azure.ResourceManager.ApiManagement）：サービス、API、製品、サブスクリプション、ポリシー、ユーザー、グループを作成します
• データプレーン：APIM ゲートウェイのエンドポイントに直接 API 呼び出しを行います

インストール

dotnet add package Azure.ResourceManager.ApiManagement
dotnet add package Azure.Identity

バージョンに関する注意：例はバージョンによって異なります。v1.3.0 を現行バージョンと見なすのではなく、対象プロジェクトでサポートされている SDK パッケージを確認して固定してください。

環境変数

AZURE_SUBSCRIPTION_ID=<your-subscription-id>
# For service principal auth (optional)
AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

認証

using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ApiManagement;

// Choose a deliberate credential chain; managed identity is preferable in hosted production
var credential = new DefaultAzureCredential();
var armClient = new ArmClient(credential);

// Get subscription
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var subscription = armClient.GetSubscriptionResource(
    new ResourceIdentifier($"/subscriptions/{subscriptionId}"));

リソース階層

ArmClient
└── SubscriptionResource
    └── ResourceGroupResource
        └── ApiManagementServiceResource
            ├── ApiResource
            │   ├── ApiOperationResource
            │   │   └── ApiOperationPolicyResource
            │   ├── ApiPolicyResource
            │   ├── ApiSchemaResource
            │   └── ApiDiagnosticResource
            ├── ApiManagementProductResource
            │   ├── ProductApiResource
            │   ├── ProductGroupResource
            │   └── ProductPolicyResource
            ├── ApiManagementSubscriptionResource
            ├── ApiManagementPolicyResource
            ├── ApiManagementUserResource
            ├── ApiManagementGroupResource
            ├── ApiManagementBackendResource
            ├── ApiManagementGatewayResource
            ├── ApiManagementCertificateResource
            ├── ApiManagementNamedValueResource
            └── ApiManagementLoggerResource

基本的なワークフロー

1. API Management サービスを作成する

using Azure.ResourceManager.ApiManagement;
using Azure.ResourceManager.ApiManagement.Models;

// Get resource group
var resourceGroup = await subscription
    .GetResourceGroupAsync("my-resource-group");

// Define service
var serviceData = new ApiManagementServiceData(
    location: AzureLocation.EastUS,
    sku: new ApiManagementServiceSkuProperties(
        ApiManagementServiceSkuType.Developer, 
        capacity: 1),
    publisherEmail: "[email protected]",
    publisherName: "Contoso");

// Create service (long-running operation - can take 30+ minutes)
var serviceCollection = resourceGroup.Value.GetApiManagementServices();
var operation = await serviceCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-apim-service",
    serviceData);

ApiManagementServiceResource service = operation.Value;

2. API を作成する

var apiData = new ApiCreateOrUpdateContent
{
    DisplayName = "My API",
    Path = "myapi",
    Protocols = { ApiOperationInvokableProtocol.Https },
    ServiceUri = new Uri("https://backend.contoso.com/api")
};

var apiCollection = service.GetApis();
var apiOperation = await apiCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-api",
    apiData);

ApiResource api = apiOperation.Value;

3. 製品を作成する

var productData = new ApiManagementProductData
{
    DisplayName = "Starter",
    Description = "Starter tier with limited access",
    IsSubscriptionRequired = true,
    IsApprovalRequired = false,
    SubscriptionsLimit = 1,
    State = ApiManagementProductState.NotPublished
};

var productCollection = service.GetApiManagementProducts();
var productOperation = await productCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "starter",
    productData);

ApiManagementProductResource product = productOperation.Value;

// Add API to product
await product.GetProductApis().CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-api");

4. サブスクリプションを作成する

var subscriptionData = new ApiManagementSubscriptionCreateOrUpdateContent
{
    DisplayName = "My Subscription",
    Scope = $"/products/{product.Data.Name}",
    State = ApiManagementSubscriptionState.Active
};

var subscriptionCollection = service.GetApiManagementSubscriptions();
var subOperation = await subscriptionCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-subscription",
    subscriptionData);

ApiManagementSubscriptionResource apimSubscription = subOperation.Value;

// Get subscription keys
var keys = await apimSubscription.GetSecretsAsync();
// Store keys only through the approved secret store; never log them.

5. API ポリシーを設定する

var policyXml = @"
<policies>
    <inbound>
        <rate-limit calls=""100"" renewal-period=""60"" />
        <set-header name=""X-Custom-Header"" exists-action=""override"">
            <value>CustomValue</value>
        </set-header>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>";

var policyData = new PolicyContractData
{
    Value = policyXml,
    Format = PolicyContentFormat.Xml
};

await api.GetApiPolicy().CreateOrUpdateAsync(
    WaitUntil.Completed,
    policyData);

6. バックアップと復元

// Backup
var backupParams = new ApiManagementServiceBackupRestoreContent(
    storageAccount: "mystorageaccount",
    containerName: "apim-backups",
    backupName: "backup-2024-01-15")
{
    AccessType = StorageAccountAccessType.SystemAssignedManagedIdentity
};

await service.BackupAsync(WaitUntil.Completed, backupParams);

// Restore
await service.RestoreAsync(WaitUntil.Completed, backupParams);

主要な型のリファレンス

型	用途
ArmClient	すべての ARM 操作のエントリーポイント
ApiManagementServiceResource	APIM サービスインスタンスを表します
ApiManagementServiceCollection	サービスの CRUD 操作用のコレクション
ApiResource	API を表します
ApiManagementProductResource	製品を表します
ApiManagementSubscriptionResource	サブスクリプションを表します
ApiManagementPolicyResource	サービスレベルのポリシー
ApiPolicyResource	API レベルのポリシー
ApiManagementUserResource	ユーザーを表します
ApiManagementGroupResource	グループを表します
ApiManagementBackendResource	バックエンドサービスを表します
ApiManagementGatewayResource	セルフホスト型ゲートウェイを表します

SKU の種類

SKU	用途	容量
Developer	開発／テスト（SLA なし）	1
Basic	エントリーレベルの本番環境	1-2
Standard	中規模のワークロード	1-4
Premium	高可用性、マルチリージョン	リージョンごとに 1-12
Consumption	サーバーレス、呼び出しごとの従量課金	該当なし

ベストプラクティス

1. WaitUntil.Completed を使用する：続行前に完了させる必要がある操作に使用します
2. WaitUntil.Started を使用する：サービスの作成（30 分以上）のような長時間の操作に使用します
3. 本番環境で使用する ID を明示的に選択する：キーをハードコードせず、資格情報チェーンのフォールバックを制限します
4. RequestFailedException を処理する：ARM API エラーに対応します
5. CreateOrUpdateAsync を使用する：冪等な操作に使用します
6. 階層をたどる：Get* メソッドを使用します（例：service.GetApis()）
7. ポリシー形式：ポリシーは XML 形式（xml/rawxml または対応するリンク形式）です。JSON は転送用のエンベロープであり、ポリシー言語ではありません
8. サービスの作成：テストでは Developer SKU が最も速く作成できます（約 15～30 分）

エラー処理

using Azure;

try
{
    var operation = await serviceCollection.CreateOrUpdateAsync(
        WaitUntil.Completed, serviceName, serviceData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    throw; // 409 is a conflict requiring diagnosis, not proof of successful existing state
}
catch (RequestFailedException ex) when (ex.Status == 400)
{
    Console.WriteLine($"Bad request: {ex.Message}");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}

リファレンスファイル

ファイル	読み取るタイミング
references/service-management.md	サービスの CRUD、SKU、ネットワーク、バックアップ／復元
references/apis-operations.md	API、操作、スキーマ、バージョン管理
references/products-subscriptions.md	製品、サブスクリプション、アクセス制御
references/policies.md	ポリシー XML のパターン、スコープ、一般的なポリシー

関連リソース

リソース	目的
API Management のドキュメント	Azure の公式ドキュメント
ポリシーリファレンス	ポリシーの完全なリファレンス
SDK リファレンス	.NET API リファレンス

使用する場合

このスキルは、概要に記載されているワークフローまたはアクションを実行する場合に適用できます。

制限事項

• タスクが上記の説明にある範囲に明確に一致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。

リソース変更と SDK の制限

これらのスニペットは、プロジェクト設定とバージョン固有のモデル型／コンストラクターを省略した個別の例であり、Azure に対してコンパイルまたは実行されていません。ResourceIdentifier／AzureLocation には Azure.Core が必要で、WaitUntil／ETag には Azure が必要です。適用前に、正確な SDK オーバーロード、必須の ETag、サポートされている SKU／リージョンの機能を確認してください。409 は別の競合や処理中の操作を示す場合があり、作成が成功したことを意味しません。開始した操作については、引き続きポーリングし、プロビジョニング状態を読み戻す必要があります。CreateOrUpdate は既存の構成を置き換える可能性があり、名前が冪等に見えるからといって無害ではありません。

プロビジョニングの前に、テナント、サブスクリプション、リソース ID、RBAC、コスト、デプロイ範囲を確認してください。アクセスレビューが完了するまで、製品は未公開のままにしてください。サブスクリプションキーだけでは、エンドユーザーの本人確認や完全な API 認可にはなりません。コンシューマーの移行と読み戻しを行いながら、一度に 1 つのキーをローテーションしてください。両方のキーをすぐに再生成しないでください。サービスの削除、サブスクリプションの一時停止、ポリシーの変更、復元には、対象についての明示的な承認と復旧計画が必要です。マネージド ID を使用したバックアップにも、実際の ID、ストレージ権限、サポート対象のティアが必要です。バックアップは、完全なロールバックを保証するものではありません。ポリシーの例には JWT 検証が含まれておらず、そのレート制限もあらゆるトラフィックに適用される上限ではありません。既存のポリシー継承を維持し、ロールアウト前にレビュー済みのリビジョンを使用してください。公開ログには生の ARM エラーボディを含めないでください。