Swagger 仕様を使用した使用できないエンドポイントの追加

Composer での ThingWorx モデルの定義 > モデル化 > 統合コネクタ > 統合コネクタの前提条件 > ODataConnector または SAPODataConnector の使用 > Swagger 仕様を使用した使用できないエンドポイントの追加

たとえば、OData 仕様の次の EntityType の定義について考えてみます。

指定された Document に PrimaryContent を追加できるエンドポイントは、OData 仕様を解析することによって ODataConnector が生成するエンドポイントリストには含まれていません。一般的に、EntityType の NavigationProperty 定義に対してバックエンドシステムによってサポートされているエンドポイントは、コネクタが生成するリストには含まれていません。したがって、これらのエンドポイントを定義する Swagger 仕様を作成してから、JSON フォーマットの仕様を SwaggerJSON プロパティの値として追加する必要があります。詳細については、ODataConnector または SAPODataConnector の使用を参照してください。

上記の例では、OData 仕様の読み取りから次のことがわかっています。

• エンドポイントへのパスは、/Documents('{ID}')/PrimaryContent の形式になります。

◦ Documents は entitySet の名前で、Document エンティティを含みます。

◦ ID は Document の Key であり、Document インスタンスを一意に識別するために使用します。ID を囲む波かっこ {} は、プレースホルダーを実際の値に置き換えてリクエストする際に指定する必要がある、必須のパスパラメータのプレースホルダーであることを示します。

◦ PrimaryContent は Document の NavigationProperty です。

• PUT は、PrimaryContent が ContentItem タイプであるために Document の PrimaryContent のアップロードをサポートする HTTP 操作です。ContentItem では HasStream プロパティが True に設定されています。

• Document の PrimaryContent としてアップロードする必要があるファイルは必須の入力であり、リクエストが正常に実行されるためには、リクエストの ContentType が multipart/form-data でなければなりません。

• エンドポイントの実行からの応答は、次のいずれかになります。

◦ スキーマが ContentItem 定義に正常に準拠している JSON オブジェクト。

◦ 無効なリクエストを示すエラー。

エンドポイントに対するリクエストを実行するためのすべての要件は、Swagger 仕様の定義を作成する前に、Google Chrome の Postman 拡張機能などのアプリケーションを使用して評価する必要があります。

Postman の要件を評価した後、Swagger Editor などのツールを使用して、エンドポイントの定義を作成します。

1. 空の paths オブジェクトを使用してエディタを起動します。

2. エンドポイントのパスと、パスがサポートする HTTP 操作を追加します。上記の例では、それぞれ "/Documents('{ID}')/PrimaryContent" と put になります。

3. ID (path パラメータ) および File (formData パラメータ) の入力パラメータ定義を追加します。

4. エンドポイントに consumes: [ multipart/form-data ], および produces: [ application/json ] というロジックを追加します。

5. エンドポイントが生成する HTTP ステータスコードによって識別される応答を追加します。

例:

◦ 成功した操作 (HTTP ステータスコード 200) は、スキーマが ContentItem 定義に準拠している JSON オブジェクトを返します。$ref プロパティを介し、ContentItem 定義への参照が示されます。

◦ 無効なリクエスト (HTTP ステータスコード 405)。

6. ContentItem 定義を追加します。スキーマについて理解するには、OData 仕様の ContentItem entityType 定義を参照してください。

7. PUT 操作の operationId とサマリーを指定します。

8. エディタで報告されたエラーを解決し、必要なパス、操作、および定義を追加した後に、Swagger 仕様を JSON ファイルとしてエクスポートします。

9. エクスポートされた JSON ファイルのコンテンツをコピーし、SwaggerJSON プロパティの値として設定します。