更新とバージョン管理
認定を経て公開されたカスタム コネクタ、またはオープンソースとして作成されたカスタム コネクタも引き続き更新することができます。 更新を実行するプロセスは、最初の公開とほとんど同じです。 主な違いは、更新を計画する際には、既存のユーザーを考慮する必要がある点です。 変更が小規模な場合でも、コネクタ定義の破壊的変更は、既存のユーザーに影響を与える可能性があります。
コネクタのトリガーやアクションは、基になる API で機能が追加または展開されるにつれて、時間の経過とともに成長したり変化したりすることがあります。 一部の変更は、単に追加だけに留まり、コネクタを使用するアプリとフロー間の規定に違反するものではありません。 新しいパラメーターの追加、返すデータの増加、またはより柔軟な入力を許可することなどは、このカテゴリに分類されます。 ただし多くの変更は、OpenAPI 仕様に記載されている規定に違反する可能性があります。
破壊的変更の例には、次のようなものが含まれます。
パラメーターの削除
特定の入力のサポート停止
入力、出力、または操作の意味と動作の変更
カスタム コネクタで記載する API は、このような破壊的変更を回避する必要があります。 異なるグループがコネクタ定義と API を維持している場合、これらのグループの同期を保つ必要があります。
カスタム コネクタと API を安全に更新するには、コネクタのユーザーが更新に対応できるような状況を提供する必要があります。 下位互換性を維持し、変更の意図を伝え、バージョン管理の属性を詳しく説明することは、コネクタの責務であり、したがって API の責務でもあります。 また、非推奨や期限切れの動作、または新しいバージョンがあることをコネクタで表示するか非表示にするかを決定するのは、ツール設計者の責務です。 こうすることで、コネクタや API を使用しているアプリケーションで不要な脆弱性を発生させることなく、動作を更新し開発することができます。
コネクタ アクションへの注釈付け
OpenAPI コンフィギュレーションを使用して、コネクタのアクションに注釈を付けることができます。これにより、それがデザイン サーフェスに提示されたときに、使用目的を伝えることができます。 たとえば、OpenAPI 拡張機能 x-ms-api-annotation を GetInvoice アクションに追加すると、そのステータスがプレビューであることを示すことができます。
その結果、このアクションが Power Automate クラウド フロー デザイナーに表示される際、アクション名の後に (プレビュー) と表示されます。
アクションの新しいバージョン
アクションのライフサイクルの中で、破壊的変更の導入が必要になることがあります。 この場合、アクションの新しいバージョンを作成することを推奨します。 元のアクションを使用している既存のユーザーに影響を与えることなく、新しいユーザーは新しいバージョンの利点を活用することができます。 一般的なプラクティスとして、概要の一部としてバージョンを示します。 このプロセスは、次のスクリーンショットのようになります。
アクションの非推奨
新しいアクションの導入後は、古いアクションを非推奨にして、新しいアプリケーションやフローで使用されないようにします。 最初に、古いアクションを表示設定セクションで詳細としてマークします。 重要とマークされたアクションがある場合は、新しい V2 アクションも重要とマークする必要があるかどうか検討します。 どちらの表示設定の変更も、新しいアクションをアクション リストの上位に配置することで、ユーザーに使用を促します。
概要や説明で、予定されている非推奨化について記載することもできます。 たとえば、請求書の取得を請求書の取得 (非推奨) に変更できます。 このようにして、アクションを非表示にすることなく、ユーザーに非推奨化されたことを示すことができます。 目的は、コネクタのユーザーが行われた変更に対応できるようにすることです。
新しいユーザー向けにアクションを非表示にし、既存のユーザーに影響しないようにするには、OpenAPI コンフィギュレーションでアクションをdeprecatedとマークします。 この変更は、Swagger エディターを使用して、OpenAPI 定義を直接編集することで行います。 アクションが非推奨にされたことを示すには、次のコマンドを操作コンフィギュレーションに追加します。
deprecated: true
コネクタの発行後、このコマンドによって、新しいフローでユーザーが選択できないように、アクションが非表示になります。
アクションのバージョン管理への準拠には多くの理由があります。 その主な理由として、ユーザーがコネクタ アクションをフローに統合する際、Logic Apps や Power Automate などのクライアントの正常な動作を確保することが挙げられます。 次のいずれかに当てはまる場合、上記の方法でアクションのバージョン管理を行なう必要があります。
アクションの新しいリビジョンが追加される。
既存のアクションによって、パラメータが追加または削除される。
既存の操作によって、入力または出力が大幅に変更される。
バージョン管理が不要な場合もありますが、その際は注意が必要です。ユーザーのアプリやフローが予期せず壊れる可能性があるエッジ ケースを見逃さないよう、十分なテストを実施する必要があります。
次の場合、バージョン管理を回避できます (十分な注意が必要)。
新しいアクションが追加される。
新しい任意のパラメータが既存のアクションに追加される。
既存のアクションによって動作が若干変更される。
コネクタ定義や基になる API に対して大きな変更を行う場合は、十分に注意してリビジョンを作成してください。