バージョン管理を使用した API の進化

[アーティクル]
06/23/2023

Azure Logic Apps、Microsoft Power Automate、または Microsoft Power Apps のカスタムコネクタは、OpenAPI 仕様ファイルを提供する必要があります。この OpenAPI 仕様により、操作と呼ばれる個別のエントリポイントが定義されます。各操作には、一意の operationId および urlPath と HttpVerb の一意の組み合わせがあります。

{
    "/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        },
        "post": {
            "summary": "Insert row",
            "description": "This operation inserts an item.",
            "operationId": "PostItem"
        }
    }
}

これらの操作は、機能の追加や拡張に伴い、徐々に拡大し、変えていくことができます。いくつかの変更は単なる追加的なもので、クライアントとサーバーの間に存在する契約を必ずしも破棄するものではありません。新しいパラメーターの追加、返すデータの増加、またはより柔軟な入力を許可することなどは、このカテゴリに分類されます。

しかし、OpenAPI 仕様で説明されているコントラクトを実際に破棄する可能性がある変更は、多数存在します。パラメーターの削除、特定の入力のサポート廃止、入力、出力、または操作自体の意味と動作の変更は、"破壊的変更" カテゴリに分類されます。

API を安全に進化させるには、クライアントがナビゲートできるパターンに従うことが重要です。下位互換性の維持、意図の伝達、バージョン管理属性を明確に記述するのは API の役割です。非推奨の操作、期限切れの操作、または新しいバージョンが提供されている可能性のある操作を表示または非表示にする役割は、クライアントが担います。こうすることで、コネクタや API を使用しているアプリケーションで不要な脆弱性を発生させることなく、動作を更新し開発することができます。

API の注釈

OpenAPI には、操作のバージョン管理を行うための組み込みサポートがありません。目的を達成するために、作業の多くが x-ms-api-annotation オブジェクトを介して行われます。このオブジェクトは、グローバルスコープと操作スコープの両方で適用されます。グローバルオブジェクトには、API 全体に適用されるプロパティが含まれています。

{
    "x-ms-api-annotation": {
        "status": "Preview"
    }
}

プロパティ	値	既定	説明設定
状態	`"Preview"` `"Production"`	`"Preview"`	API 全体の状態—プレビューからスタートし、使用状況や安定性に応じてプロダクションへとエスカレーションします

操作スコープでは、このオブジェクトには、より詳細なプロパティが含まれています。また、オブジェクトの外部には、バージョン管理の進化プロセスに適用され、プロセスに関与する追加のプロパティがあります。

{
    "deprecated": true,
    "x-ms-api-annotation": {
        "status": "Production",
        "family": "MyOperation",
        "revision": 2
    }
}

プロパティ	値	既定	内容
deprecated	`null` `false` `true`	`false`	操作が非推奨となっているかどうかを示します
x-ms-visibility	`null` `""` `"Important"` `"Advanced"` `"Internal"`	`""`	この操作の意図された表示設定とプロミネンスを示します (`null` または `""` は通常の状態を意味します)
状態	`"Preview"` `"Production"`	`"Production"`	操作の状態です—これは、API 自体の状態とは異なる場合がありますが、指定されていない場合は、最上位レベルの API の状態を受け継ぎます
ファミリー	{common operation name}	operationName	この操作のすべてのリビジョンに適用される名前です
リビジョン	数値 (1,2,3...)	`1`	指定された操作ファミリのリビジョンです
有効期限	ISO8601 の日付	(なし)	クライアントへの省略可能なヒントで、サポートの終了予定を示します

非推奨: この操作をクライアントに使用してほしくない場合は true に設定します。このプロパティは、OpenAPI 固定フィールド仕様にあります。

可視性: 操作の対象となる相対プロミネンスのインジケーターです。 "Important" の表示設定は、操作をリストの上部に目立つように表示する必要があることを示します。 normal 表示設定 (null または空の文字列 "" で示されます) は既定値です。これは操作がリストに表示されることを示し、多くの場合、重要な操作の後に表示されます。 "Advanced" 表示設定は、操作がリストの一番下にあるか、最初は expando コントロールで隠れている可能性があることを示します。 Advanced 操作は、使いづらかったり、人気がなかったり、適用範囲が狭かったりする可能性があります。 "Internal" 表示設定は、操作がユーザーに公開されないようにして、内部でのみ使用する必要があることを示します。 Internal 操作はプログラム的には有用で価値がありますが、エンドユーザー向けではありません。また Internal 操作は、API から削除してしまうと破壊的変更を引き起こすことがあるため、実際に削除せず、UI に表示されないようにするために、非推奨プロセス中に非推奨としてマークされている場合もあります。

状態: API または操作の安定性を示します。 "Preview" は、操作または API が新しく未確認の可能性があることを示します。プレビューは、運用システムで慎重に依存関係を想定する必要があることを示します。操作や AP Iがさらに確立され、信頼性、成功率、拡張性などの基準を満たしていることが証明されたら、意図的に "Production" の状態にアップグレードすることができます。

次のメトリック要件は、通常、"Production" 状態のシーク操作に適用されます。

80% の成功率が 3 週間
- 2xx の範囲の HTTP 応答コードの割合として定義されます
99.9% の信頼性が 3 週間にわたって継続
- 5xx の範囲以外の HTTP 応答コードの割合として定義されます (502、504、および 520 はこの計算から除外)

ファミリー: 概念的には同じ操作であっても、リビジョンが異なり、その違いが破壊的変更の可能性がある操作間の関係を示します。複数の操作それぞれがお互いのリビジョンであると見なされ、一意のリビジョン番号によってシーケンス処理されている場合、その操作は同じファミリー名を共有します。

リビジョン: 操作ファミリー内の操作の進化的順序を示します。ファミリー内の各操作には、順序を示す整数のインデックスであるリビジョンが指定されます。空のリビジョンは、リビジョン 1 と見なされます。新しい操作バージョンが利用可能になったら、クライアントはそれを目立つように表示し、積極的に勧める必要があります。ただし、まだ非推奨になっていない古いリビジョンも選択できるようにします。

期限: 省略可能。操作のサポートが保証されなくなる潜在的な有効期限を示します。これは非推奨の操作に対してのみ設定する必要があり、現時点ではどのインターフェイスにも反映されていません。

操作の有効期間

操作には、例で示すことができる予測可能な有効期間があります。

開始ポイント

最初は、操作が必ずしもリビジョンを示しているとは限りません。これらの操作には既定値が適用されるため、operationId に相当するファミリー名でリビジョン 1 と見なされます。

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems"
        }
    }
}

これは、次のより明示的な定義と同等です:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
}

操作の開始

API のほとんどが、操作の追加によって進化していきます。たとえば、新しいメソッドや既存のメソッドの新しいリビジョンによって進化していきます。新しいリビジョンを安全に開始するには、OpenAPI 仕様を次のように調整します。

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (V1 - downplayed)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": false,
            "x-ms-visibility": "advanced",
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows (V2 - new hotness)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Preview",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

重要

GetItems V2 には一意の operationId があり、最初はプレビュー状態で表示されることに注意してください。また、GetItems v1 には高度な表示設定が指定されているため、目立たないように表示されることにも注意してください。

操作の非推奨化

既存の V1 エントリポイントが価値を提供し続けていて、そのエントリポイントを終了するやむを得ない理由がなければ、その既存の V1 エントリポイントが永遠に残ることがあります。そうは言っても、V2 エントリポイントの多くが、V1 エントリポイントに意図的に取って代わります。これを安全に行うには、元の操作に対するすべてのトラフィックが公称ゼロにならなければなりません。テレメトリがこの状況を確認したら、次の変更を行うことができます:

{
    "/{list}/items": {
        "get": {
            "summary": "Get rows (deprecated)",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems",
            "deprecated": true,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 1
            }
        }
    }
    "/v2/{list}/items": {
        "get": {
            "summary": "Get rows",
            "description": "This operation gets a list of items.",
            "operationId": "GetItems_V2",
            "deprecated": false,
            "x-ms-api-annotation": {
                "status": "Production",
                "family": "GetItems",
                "revision": 2
            }
        }
    }
}

重要

GetItems V1 が非推奨としてマークされていることに注意してください。これは操作を非推奨にする最終的な移行です。以上で GetItems V1 が完全に GetItems V2 に置き換えられました。

煩雑な理由

操作のバージョン管理から離れられない理由は多数あります。主にこれにより、ユーザーがコネクタ操作をデータフローに統合するときに、Azure Logic Apps と Power Automate などのクライアントが確実かつ正確に動作し続けます。以下の場合は必ず、上記の方法を使って操作のバージョン管理を行う必要があります:

操作の新しいリビジョンが追加された
既存の操作でパラメーターが追加または削除された
既存の操作によって、入力または出力が大幅に変更される

詳細

バージョン管理—を回避できる場合もありますが、バージョン管理を行わない場合は、細心の注意を払う必要があります。また、十分なテストを行って、ユーザーが予期せずに破損する可能性のあるエッジケースを見落とさないようにしてください。バージョン管理が不要な場合の簡単な注意事項を次に示します。

新しい操作が追加される。

この場合、既存のクライアントが特に破損することはありません。
既存の操作に新しい省略可能なパラメーターが追加された場合。

この場合、既存の呼び出しが中断されることはありませんが、慎重に検討する必要があります。
既存の操作によって動作が微妙に変化する場合。

変更の性質とユーザーの依存関係に基づいて、既存の呼び出し元が破損することはありません。これは最も不安定です。入力の受け入れ、出力の生成、タイミング、または処理における大きな違いが、変更リスクを判断しづらい方法で、操作の動作に影響を及ぼすことがあるためです。

重要な API の変更を行う場合は、細心の注意を払ってリビジョンを繰り返すことを推奨します。

フィードバックを提供する

コネクタプラットフォームの問題点や新機能のアイデアなどのフィードバックをお待ちしています。フィードバックを提供するには、「問題を送信するか、コネクタに関するヘルプを入手する」にアクセスし、フィードバックの種類を選択します。