API のインポートに関する制限事項と既知の問題
適用対象: すべての API Management レベル
API をインポートする際は、いくつかの制限事項が発生する場合や、正常にインポートするために問題を特定して修正する必要があることがあります。 この記事では、次の内容について説明します。
- OpenAPI インポート時の API Management の動作。
- OpenAPI インポートの制限事項と OpenAPI エクスポートのしくみ。
- WSDL と WADL のインポートの要件と制限事項。
OpenAPI インポート時の API Management
OpenAPI のインポート時に、API Management は次のことを行います。
- 必須とマークされているクエリ文字列パラメーターのみを確認する。
- 既定では、必要なクエリ文字列パラメーターを必要なテンプレート パラメーターに変換します。
仕様で必要なクエリ パラメーターを API Management のクエリ パラメーターに変換する場合は、ポータルで API を作成するときに、[操作テンプレートにクエリ パラメーターを含める] 設定を無効にします。 また、APIs - Create or Update REST API を使用して API の translateRequiredQueryParameters
プロパティを query
に設定することで、これを実現することもできます。
GET、HEAD、および OPTIONS 操作については、OpenAPI 仕様で定義されている場合、API Management は要求本文パラメーターを破棄します。
OpenAPI/Swagger のインポートの制限事項
OpenAPI ドキュメントのインポート中にエラーが発生した場合は、事前に以下のどちらかで検証を行っていることを確認します。
- Azure portal のデザイナーを使用する ([デザイン] > [フロント エンド] > [OpenAPI 仕様エディター])、または
- Swagger エディターなどのサードパーティー ツールを使用する。
全般
URL テンプレートの要件
要件 | 説明 |
---|---|
必須パスとクエリ パラメーターの一意の名前 | OpenAPI の場合:
|
定義済みの URL パラメーター | URL テンプレートの一部である必要があります。 |
利用可能なソース ファイルの URL | 相対サーバー URL に適用されます。 |
\$ref ポインター |
外部ファイルを参照できません。 |
OpenAPI の仕様
サポートされているバージョン
API Management は以下のみをサポートします。
- OpenAPI バージョン 2。
- OpenAPI バージョン 3.0.x (最大バージョン 3.0.3)。
- OpenAPI バージョン 3.1 (インポートのみ)
サイズの制限
サイズ制限 | 説明 |
---|---|
最大 4 MB | OpenAPI 仕様を API Management にインラインでインポートした場合。 |
Azure Resource Manager API 要求サイズ | API Management サービスからアクセスできる場所の URL 経由で OpenAPI ドキュメントが提供される場合。 「Azure サブスクリプションの制限」を参照してください。 |
サポートされる拡張機能
以下の拡張機能のみがサポートされています。
拡張機能 | 説明 |
---|---|
x-ms-paths |
|
x-servers |
OpenAPI 2 用の OpenAPI 3 servers オブジェクトのバックポート。 |
サポートされていない拡張機能
拡張機能 | 説明 |
---|---|
Recursion |
API Management では、再帰的に定義された定義はサポートされません。 たとえば、自身を参照するスキーマなどです。 |
Server オブジェクト |
API 操作レベルでサポートされていません。 |
Produces キーワード |
API によって返される MIME の種類について説明します。 サポートされていません。 |
カスタム拡張機能
- インポート時に無視されます。
- エクスポート用に保存または予約されません。
サポートされていない定義
API 操作に対するインライン スキーマ定義はサポートされていません。 スキーマ定義:
- API スコープで定義されます。
- API 操作の要求または応答のスコープで参照できます。
無視される定義
セキュリティ定義は無視されます。
定義の制限
クエリ パラメーターをインポートする場合は、既定の配列シリアル化メソッド (style: form
、 explode: true
) のみがサポートされます。 OpenAPI 仕様のクエリ パラメーターの詳細については、シリアル化の仕様を参照してください。
Cookie に定義されているパラメーターは、サポートされていません。 引き続きポリシーを使用して、Cookie の内容をデコードおよび検証できます。
OpenAPI バージョン 2
OpenAPI バージョン 2 のサポートは、JSON 形式のみに制限されています。
"Form" 型パラメーターはサポートされていません。 ポリシーを引き続き使用して、 application/x-www-form-urlencoded
と application/form-data
のペイロードをデコードおよび検証できます。
OpenAPI バージョン 3.x
API Management では、次の仕様バージョンがサポートされています。
- OpenAPI 3.0.3
- OpenAPI 3.1.0 (インポートのみ)
HTTPS URL
- 複数の
servers
が指定されている場合、API Management では、最初に見つかった HTTPS URL が使用されます。 - HTTPS URL がない場合、サーバーの URL は空です。
サポートされています
example
サポートされていない
OpenAPI バージョン 3.0.x または OpenAPI バージョン 3.1.x には次のフィールドが含まれていますが、サポートされていません。
Object | フィールド |
---|---|
OpenAPI | externalDocs |
情報 | summary |
Components |
|
PathItem |
|
操作 |
|
パラメーター |
|
OpenAPI のインポート、更新、およびエクスポートのメカニズム
全般
API Management サービスからエクスポートされる API 定義は:
- 主に API Management サービスでホストされる API を呼び出す必要がある外部アプリケーションを対象としています。
- 同じ、または別の API Management サービスにインポートするためのものではありません。
さまざまなサービスまたは環境にわたる API 定義の構成管理については、Git での API Management サービスの使用に関するドキュメントを参照してください。
OpenAPI のインポートを使用して新しい API を追加する
OpenAPI ドキュメントで見つかった操作ごとに、次のように新しい操作が作成されます。
Azure リソース名を
operationId
に設定します。operationId
値は正規化されます。operationId
が指定されていない (存在しないか、null
であるか、空である) 場合、Azure リソース名の値は、HTTP メソッドとパス テンプレートを組み合わせて生成されます。- たとえば、「
get-foo
」のように入力します。
- たとえば、「
表示名を
summary
に設定します。summary
値:- そのままインポートされます。
- 長さは 300 文字に制限されています。
summary
が指定されていない場合 (存在しないか、null
であるか、空である)、表示名の値はoperationId
に設定されます。
operationId
の正規化規則
- 小文字に変換します。
- 英数字以外の文字のシーケンスをそれぞれ 1 つのダッシュで置き換えます。
- たとえば、
GET-/foo/{bar}?buzz={quix}
はget-foo-bar-buzz-quix-
に変換されます。
- たとえば、
- 両側のダッシュがトリミングされます。
- たとえば、
get-foo-bar-buzz-quix-
はget-foo-bar-buzz-quix
になります
- たとえば、
- リソース名の最大制限より 4 文字少ない 76 文字に収まるように切り捨てます。
- 残りの 4 文字は、必要に応じて
-1, -2, ..., -999
の形式で、重複除去サフィックスに使用します。
OpenAPI のインポートを使用して既存の API を更新する
インポート中、既存の API 操作は:
- OpenAPI ドキュメントで説明されている API に一致するように変更されます。
operationId
値を既存の操作の Azure リソース名と比較することによって、OpenAPI ドキュメント内の操作と照合されます。- 一致が見つかった場合、既存の操作のプロパティは "インプレースで" 更新されます。
- 一致が見つからない場合:
- 新しい操作は、HTTP メソッドとパス テンプレートを組み合わせることによって作成されます (たとえば、
get-foo
)。 - 新しい操作ごとに、インポートにより、同じ HTTP メソッドとパス テンプレートを使用する既存の操作からのポリシーのコピーが試みられます。
- 新しい操作は、HTTP メソッドとパス テンプレートを組み合わせることによって作成されます (たとえば、
一致しない既存の操作はすべて削除されます。
インポートをより予測しやすくするには、次のガイドラインに従ってください。
- すべての操作に対して
operationId
プロパティを指定します。 - 最初のインポート後に
operationId
を変更しないでください。 operationId
と HTTP メソッドまたはパス テンプレートを同時に変更しないでください。
operationId
の正規化規則
- 小文字に変換します。
- 英数字以外の文字のシーケンスをそれぞれ 1 つのダッシュで置き換えます。
- たとえば、
GET-/foo/{bar}?buzz={quix}
はget-foo-bar-buzz-quix-
に変換されます。
- たとえば、
- 両側のダッシュがトリミングされます。
- たとえば、
get-foo-bar-buzz-quix-
はget-foo-bar-buzz-quix
になります
- たとえば、
- リソース名の最大制限より 4 文字少ない 76 文字に収まるように切り捨てます。
- 残りの 4 文字は、必要に応じて
-1, -2, ..., -999
の形式で、重複除去サフィックスに使用します。
API を OpenAPI としてエクスポートする
各操作について、次のようになります。
- Azure リソース名は
operationId
としてエクスポートされます。 - 表示名は
summary
としてエクスポートされます。
正規化 operationId
は、エクスポート時ではなくインポート時に行われることに注意してください。
WSDL
WSDL ファイルを使用して、SOAP パススルー と SOAP-to-REST の API を作成できます。
SOAP バインディング
- "document" と "literal" のエンコード スタイルの SOAP バインディングのみがサポートされています。
- "rpc" スタイルまたは SOAP エンコードはサポートされていません。
インポートとインクルード
wsdl:import
、xsd:import
とxsd:include
ディレクティブはサポートされていません。 代わりに、依存関係を 1 つのドキュメントにマージする必要があります。WSDL ファイル内の
wsdl:import
、xsd:import
、xsd:include
の依存関係を解決およびマージするオープンソース ツールについては、この GitHub リポジトリを参照してください。
WS-* 仕様
WS-* 仕様を組み込んだ WSDL ファイルはサポートされていません。
複数部分を含むメッセージ
このメッセージ型はサポートされていません。
WCF wsHttpBinding
- Windows Communication Foundation で作成された SOAP サービスは、
basicHttpBinding
を使用する必要があります。 `SUSER_SID` はサポートされていません。
MTOM
MTOM
を使用するサービスが機能する "MTOM
"。- 現時点では、正式なサポートは提供されていません。
再帰
- 再帰的に定義された型は、API Management ではサポートされていません。
- たとえば、自身の配列の参照などです。
複数の名前空間
1 つのスキーマで複数の名前空間を使用できますが、メッセージ部分を定義するために使用できるのはターゲット名前空間だけです。 これらの名前空間は、他の入力または出力の要素を定義するために使用されます。
ターゲット以外の名前空間は、エクスポート時に保持されません。 他の名前空間を使用してメッセージ部分を定義した WSDL ドキュメントをインポートできますが、すべてのメッセージ部分では、エクスポート時に WSDL ターゲットの名前空間が使用されます。
複数のエンドポイント
WSDL ファイルでは、1 つ以上の wsdl:service
および wsdl:port
要素によって、複数のサービスとエンドポイント (ポート) を定義できます。 ただし、API Management ゲートウェイは、1 つのサービスとエンドポイントにのみ要求をインポートおよびプロキシ経由にできます。 WSDL ファイルに複数のサービスまたはエンドポイントが定義されている場合は、wsdlSelector プロパティを使用して、API をインポートするときにターゲット サービス名とエンドポイントを特定します。
ヒント
複数のサービスとエンドポイント間で要求を負荷分散する場合は、負荷分散されたバックエンド プールを構成することを検討してください。
配列
SOAP-to-REST の変換では、次の例に示すラップされた配列のみがサポートされています。
<complexType name="arrayTypeName">
<sequence>
<element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
<complexType name="typeName">
<sequence>
<element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
<element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
<element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
</sequence>
</complexType>
WADL
現時点では、WADL のインポートに関する既知の問題はありません。