API のインポートに関する制限事項と既知の問題

[アーティクル]
04/24/2024

適用対象: すべての 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 の場合: パラメーター名は、パス、クエリ、ヘッダーなどの場所でのみ一意である必要があります。 API Management の場合: パスのクエリの両方のパラメーターによって操作を区別できます。 OpenAPI ではこの区別がサポートされていないため、URL テンプレート全体でパラメーター名を一意にする必要があります。
定義済みの 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`	URL のクエリパラメーターで区別されるパスを定義できます。 AutoRest のドキュメントで説明されています。
`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	`responses` `parameters` `examples` `requestBodies` `headers` `securitySchemes` `links` `callbacks`
PathItem	`trace` `servers`
操作	`externalDocs` `callbacks` `security` `servers`
パラメーター	`allowEmptyValue` `style` `explode` `allowReserved`

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 メソッドとパステンプレートを使用する既存の操作からのポリシーのコピーが試みられます。

一致しない既存の操作はすべて削除されます。

インポートをより予測しやすくするには、次のガイドラインに従ってください。

すべての操作に対して 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 のインポートに関する既知の問題はありません。