オプション2: ファイルインポートによるサービスコネクタの生成
WSDL（Web Service Definition Language）ファイル、Swagger 2.0 JSONファイル、OpenAPI 3.0 JSONファイルまたはYAMLファイルをインポートして、アプリケーションの統合サービスコネクタを作成できます。
WSDLファイルからのサービスコネクタの作成
WSDLファイルをインポートして、複数の操作を行うサービスコネクタを容易に作成することができます。WSDLファイルをインポートしてサービスコネクタを作成するには、［WSDLからのサービスコネクタ］ウィザードを使用します。WSDLファイルを指定すると、アプリケーション統合によってファイルが解析され、操作がロードされます。
また、チェックボックス、日付、日時、整数、数値、テキスト、または入力フィールド、出力フィールド、およびプロセスオブジェクトフィールドの時刻などの単純タイプのリストを設定することもできます。WSDLファイルをインポートする前に、次のサンプル画像に示すように、単純形のリストを設定します。
インポート中にエラーが発生すると、ウィザードの［進行状況］タブの［エラー/警告］にエラーが表示されます。エラーに対処したら、WSDLファイルを再びインポートできます。
1アプリケーションの統合の左側のナビゲーションバーにある［新規］をクリックします。
［新しいアセット］ダイアログボックスが表示されます。
次の図は、［新しいアセット］ダイアログボックスを示しています。
2［サービスコネクタ］ > ［WSDLのサービスコネクタ］をクリックし、［作成］をクリックします。
次の図に示すように、［WSDLソース］タブがある［WSDLからの新規サービスコネクタ］ダイアログボックスが表示されます。
3サービスコネクタの名前、場所、説明を指定します。
4［WSDLファイル］セクションで、次のいずれかのオプションを使用して、インポートするWSDLファイルを指定します。
- - ローカルシステムのWSDLファイルを使用するには、［ファイル］を選択してからWSDLファイルを選択します。
自己完結型の.wsdlファイルと.xsdスキーマファイルを含む.wsdlファイルまたは.zipファイルを1つ選択できます。
- - WSDLファイルを含むURLを使用するには、［URL］を選択します。［WSDL URL］フィールドと［認証の使用］フィールドが表示されます。WSDLファイルを含むURLを［WSDL URL］フィールドに入力します。［認証の使用］オプションを選択して、WSDL URLにアクセスするためのユーザー名とパスワードを指定します。
注: パスワードにアンパサンド（&）文字が含まれている場合は、サービスコネクタをテストすると、操作が失敗します。また、アプリケーション接続およびプロセスで同じサービスコネクタを使用している場合は、プロセス呼出しも失敗します。
5［次へ］をクリックします。
［サービスと操作］タブが表示されます。
次の図は、［サービスと操作］タブを示します。
6インポートしたWSDLファイルから使用するサービスを［サービス名］リストから選択します。
サービスコネクタが要求を送信するURLが［サービスURL］フィールドに表示されます。このURLは編集できません。
7サービスコネクタが使用するポートを［サービスポート］リストから選択します。
8［操作］セクションで、サービスコネクタで提供する操作を選択します。
選択する操作は、プロセスを作成し、サービスコネクタを使用するときに、アクションとして使用できます。
9［次へ］をクリックします。
［サマリ］タブが表示されます。
次の図は、［サマリ］タブを示しています。
10サービスコネクタの設定を確認します。
11［インポートの開始］をクリックします。
アプリケーション統合によってWSDLファイルのインポートが開始され、ステータスが［進行状況］タブに表示されます。［進行状況］タブは、インポートが正常に完了したか、失敗したか、警告が伴う状態で完了したかを示します。
次の図は、［進行状況］タブを示しています。
注: ダイアログボックスを閉じるかインポートをキャンセルすると、インポートプロセスが停止し、サービスコネクタは作成されません。
インポートが失敗するか、警告を伴う状態で完了した場合は、［エラー/警告］タブをクリックして、インポートが正常に完了しなかった理由を確認します。問題を修正したら、WSDLファイルを再びインポートできます。
次の図は、成功したインポートを示しています。
12［完了］をクリックしてサービスコネクタを保存します。
修飾要素が含まれるWSDLファイル
ユーザー定義のデータ型を持つWSDLファイルがある場合、名前空間のプレフィックスと型名を追加して、修飾要素が含まれるWSDLファイルを作成できます。このWSDLファイルを使用して、サービスコネクタを作成できます。
ユーザー定義のデータ型が含まれるWSDLファイルからサービスコネクタを作成できます。名前空間のプレフィックスと型名をユーザー定義のデータに追加して、修飾要素が含まれるWSDLファイルを作成します。このWSDLファイルを使用して、サービスコネクタを生成できます。名前空間のプレフィックスは、プロセスオブジェクトには表示されずに、正しいペイロードが表示されます。
例として、ユーザー定義の要素RecordIdとAddressCompleteが含まれるWSDLファイルを考えます。
まず、型名「Address」を持つスキーマを定義します。次に示すのは、complexType名Addressを持つサンプルスキーマです。
xs:complexType name="Address">
<xs:sequence>
<xs:element minOccurs="0" maxOccurs="1" name="RecordId" type="xs:string" />
<xs:element minOccurs="0" maxOccurs="1" name="AddressComplete" type="xs:string" />
</xs:sequence>
</xs:complexType>
<xs:element minOccurs="0" maxOccurs="1" name="Address" type="tns:Address" />
次に、WSDLファイルで、名前空間プレフィックス「tns」を次のサンプルのように追加します。
<wsdl:message name="InputRequest">
<wsdl:part name="parameters" element="tns:Address" />
</wsdl:message>
<wsdl:portType name="AddressValidationSoap">
<wsdl:operation name="Process">
<wsdl:input message="tns:InputRequest" />
...
</wsdl:operation>
</wsdl:portType>
このWSDLファイルを使用して、サービスコネクタを作成できます。2つのフィールドRecordIdとAddressCompleteを持つAddressプロセスオブジェクトを取得します。
繰り返し要素が含まれるWSDLファイル
ネストした繰り返し要素を持つWSDLファイルからサービスコネクタを作成できます。
例えば、ネストした繰り返し要素の「shelf」と「book」を持つ、次のWSDLとWSDLスキーマファイルを考えます。
このWSDLとWSDLスキーマファイルを使用して、WSDLからサービスコネクタツールによってサービスコネクタを作成できます。サービスコネクタをインポートすると、Library、Shelf、およびBookの3つのプロセスオブジェクトがあります。親オブジェクトを選択すると、下部パネルの右側にネストされたオブジェクトも表示されます。
elementFormDefault
WSDLスキーマのelementFormDefault属性が含まれるWSDLファイルを使用できます。
WSDLファイルには、elementFormDefault="qualified"またはelementFormDefault="unqualified"を含めることができます。
選択要素
選択スキーマ要素を使用して、WSDLファイル内にペイロードを作成できます。
if要素を使用して、要求に表示すべきものを示します。
サービスコネクタへのWSDLは、最上位レベルの選択要素を考慮します。これは、WSDLスキーマファイルにネストした選択要素がある場合、サービスコネクタへのWSDLが最初の選択要素を取得します。
Swagger JSONファイルからのサービスコネクタの作成
Swagger 2.0 JSONファイルをインポートして、複数の操作を行うサービスコネクタを容易に作成することができます。Swagger JSONファイルをインポートしてサービスコネクタを作成するには、［Swaggerからのサービスコネクタ］ウィザードを使用します。Swagger JSONファイルを指定すると、アプリケーション統合によってファイルが解析され、操作がロードされます。
また、チェックボックス、日付、日時、整数、数値、テキスト、または入力フィールド、出力フィールド、およびプロセスオブジェクトフィールドの時刻などの単純タイプのリストを設定することもできます。Swagger JSONファイルをインポートする前に、次のサンプル画像に示すように、単純型のリストを設定します。
インポート中にエラーが発生すると、ウィザードの［進行状況］タブの［エラー/警告］にエラーが表示されます。エラーに対処したら、Swagger JSONファイルを再びインポートできます。
1アプリケーションの統合の左側のナビゲーションバーにある［新規］をクリックします。
［新しいアセット］ダイアログボックスが表示されます。
次の図は、［新しいアセット］ダイアログボックスを示しています。
2［サービスコネクタ］ > ［Swaggerのサービスコネクタ］をクリックし、［作成］をクリックします。
次の図に示すように、［Swaggerソース］タブがある［Swaggerからの新規サービスコネクタ］ダイアログボックスが表示されます。
3サービスコネクタの名前、場所、説明を指定します。
4［Swaggerファイル］セクションで、次のいずれかのオプションを使用して、インポートするSwagger JSONファイルを指定します。
- - ローカルシステムのSwagger JSONファイルを使用するには、［ファイル］を選択してからSwagger JSONファイルを選択します。
- - Swagger JSONファイルが含まれるURLを使用するには、［URL］を選択します。［Swagger URL］フィールドと［認証の使用］フィールドが表示されます。Swagger JSONファイルを含むURLを［Swagger URL］フィールドに入力します。［認証の使用］オプションを選択して、Swagger JSON URLにアクセスするためのユーザー名とパスワードを指定します。
注: パスワードにアンパサンド（&）文字が含まれている場合は、サービスコネクタをテストすると、操作が失敗します。また、アプリケーション接続およびプロセスで同じサービスコネクタを使用している場合は、プロセス呼出しも失敗します。
5［次へ］をクリックします。
［サービスと操作］タブが表示されます。
次の図は、［サービスと操作］タブを示します。
6［操作］セクションで、サービスコネクタで提供する操作を選択します。
選択する操作は、プロセスを作成し、サービスコネクタを使用するときに、アクションとして使用できます。
7［次へ］をクリックします。
［サマリ］タブが表示されます。
次の図は、［サマリ］タブを示しています。
8サービスコネクタの設定を確認します。
9［インポートの開始］をクリックします。
アプリケーション統合によってSwagger JSONファイルのインポートが開始され、ステータスが［進行状況］タブに表示されます。［進行状況］タブは、インポートが正常に完了したか、失敗したか、警告が伴う状態で完了したかを示します。
次の図は、［進行状況］タブを示しています。
注: ダイアログボックスを閉じるかインポートをキャンセルすると、インポートプロセスが停止し、サービスコネクタは作成されません。
インポートが失敗するか、警告を伴う状態で完了した場合は、［エラー/警告］タブをクリックして、インポートが正常に完了しなかった理由を確認します。問題を修正したら、Swagger JSONファイルを再びインポートできます。
次の図は、成功したインポートを示しています。
10［完了］をクリックしてサービスコネクタを保存します。
Swaggerファイルに関するルールおよびガイドライン
Swaggerファイルをインポートしてサービスコネクタを作成する場合は、次のルールとガイドラインを考慮してください。
OpenAPI 3.0ファイルからのサービスコネクタの作成
OpenAPI 3.0 JSONファイルまたはYAMLファイルをインポートして、複数の操作を行うサービスコネクタを容易に作成することができます。OpenAPI 3.0ファイルをインポートしてサービスコネクタを作成するには、［OpenAPI 3.0からのサービスコネクタ］ウィザードを使用します。OpenAPI 3.0ファイルを指定すると、アプリケーション統合によってファイルが解析され、操作がロードされます。
また、チェックボックス、日付、日時、整数、数値、テキスト、または入力フィールド、出力フィールド、およびプロセスオブジェクトフィールドの時刻などの単純タイプのリストを設定することもできます。OpenAPI 3.0ファイルをインポートする前に、次のサンプル画像に示すように、単純型のリストを設定します。
インポート中にエラーが発生すると、ウィザードの［進行状況］タブの［エラー/警告］にエラーが表示されます。エラーに対処したら、OpenAPI 3.0ファイルを再びインポートできます。
1アプリケーションの統合の左側のナビゲーションバーにある［新規］をクリックします。
［新しいアセット］ダイアログボックスが表示されます。
次の図は、［新しいアセット］ダイアログボックスを示しています。
2［サービスコネクタ］ > ［OpenAPI 3.0からのサービスコネクタ］をクリックし、［作成］をクリックします。
次の図に示すように、［OpenAPI 3.0ソース］タブが表示された［OpenAPI 3.0からの新規サービスコネクタ］ダイアログボックスが表示されます。
3サービスコネクタの名前、場所、説明を指定します。
4［OpenAPI 3.0ファイル］セクションで、次のいずれかのオプションを使用して、インポートするOpenAPI 3.0ファイルを指定します。
- - ローカルシステムのOpenAPI 3.0ファイルを使用するには、［ファイル］を選択してからOpenAPI 3.0 JSONファイルまたはYAMLファイルを選択します。
単一の.jsonファイルか.yamlファイル、または、自己完結型の.jsonファイルか.yamlファイルを含む単一の.zipファイルを選択することもできます。
- - OpenAPI 3.0ファイルを含むURLを使用するには、［URL］を選択します。［OpenAPI 3.0 URL］フィールドと［認証の使用］フィールドが表示されます。［OpenAPI 3.0 URL］フィールドに、OpenAPI 3.0 JSONファイルまたはYAMLファイルを含むURLを入力します。［認証の使用］オプションを選択して、OpenAPI 3.0 URLにアクセスするためのユーザー名とパスワードを指定します。
注: パスワードにアンパサンド（&）文字が含まれている場合は、サービスコネクタをテストすると、操作が失敗します。また、アプリケーション接続およびプロセスで同じサービスコネクタを使用している場合は、プロセス呼出しも失敗します。
5［次へ］をクリックします。
［サービスと操作］タブが表示されます。
次の図は、［サービスと操作］タブを示しています。
6［サービスURL］リストで、インポートしたOpenAPI 3.0ファイルから使用するエンドポイントを選択して、サービスコネクタを作成します。
7［操作］セクションで、サービスコネクタで提供する操作を選択します。
選択する操作は、プロセスを作成し、サービスコネクタを使用するときに、アクションとして使用できます。
8［次へ］をクリックします。
［サマリ］タブが表示されます。
次の図は、［サマリ］タブを示しています。
9サービスコネクタの設定を確認します。
10［インポートの開始］をクリックします。
アプリケーション統合によってOpenAPI 3.0ファイルのインポートが開始され、ステータスが［進行状況］タブに表示されます。［進行状況］タブは、インポートが正常に完了したか、失敗したか、警告が伴う状態で完了したかを示します。
次の図は、［進行状況］タブを示しています。
注: ダイアログボックスを閉じるかインポートをキャンセルすると、インポートプロセスが停止し、サービスコネクタは作成されません。
インポートが失敗するか、警告を伴う状態で完了した場合は、［エラー/警告］タブをクリックして、インポートが正常に完了しなかった理由を確認します。問題を修正したら、OpenAPI 3.0ファイルを再びインポートできます。
11［完了］をクリックしてサービスコネクタを保存します。
HTTP操作
DELETE、PUT、POST、PATCH、およびGET HTTPの各操作が含まれるSwaggerファイルをインポートできます。
生成するサービスコネクタは、SwaggerファイルのHTTP操作に対応するアクションを持ちます。Swaggerファイルに複数のHTTP操作がある場合、サービスコネクタは複数のアクションを持ちます。
例えば、POST HTTP操作が1つあるSwaggerファイルを使用する場合、得られるのはPOSTアクションが1つあるサービスコネクタです。
次の図は、Swaggerファイル内の1つのPOST HTTP操作を示します。
次の図は、先行するSwaggerファイルを使用するときに取得する、サービスコネクタのアクションを示します。
Add Petアクションが動詞POSTに対応しています。
JSONペイロード
異なるタイプのJSONペイロードを持つSwaggerファイルをインポートできます。生成するサービスコネクタは、SwaggerファイルのJSONペイロードを反映します。
次の表は、使用できるJSONペイロード機能、Swaggerサンプルの抜粋、および対応するサービスコネクタの入力フィールドを示します。
JSONペイロードの機能 | サンプルSwaggerコンテンツ | サービスコネクタの入力フィールド |
|---|
オブジェクトのリスト | | |
参照 | | |
単一の選択列挙 | | |
単純型 | | |
添付ファイル | | |
単純型のリスト | | |
複数の選択列挙 | | |
他のオブジェクトリストへの参照付きオブジェクト | | |
必須要素とNULL可能要素
ファイルをインポートしてサービスコネクタを生成する前に、WSDLファイル、Swagger JSONファイル、およびOpenAPI 3.0 JSONファイルまたはYAMLファイルで、プロセスオブジェクトフィールドを必須およびNULL可能として定義できます。
WSDLファイルで、フィールドをNULL可能として定義するには、フィールド要素でnillable属性を"true"に設定します。nillable属性を指定しない場合、デフォルトでは、フィールドはNULL可能ではないものとして設定されます。フィールドを必須として設定しない場合は、フィールド要素でminOccurs属性を"0"に設定します。minOccurs属性を指定しない場合、デフォルトでは、フィールドは必須と見なされます。
例えば、ProcessObjectReqという名前のスキーマを持つWSDLファイルがあるとします。このスキーマは複合型で、NameとIDという2つの要素を含んでいます。IDフィールドをNULL可能とし、必須としない場合は、次のサンプルに示すように、nillable属性を"true"に設定し、minOccurs属性を"0"に設定します。
<xsd:complexType name=”ProcessObjectReq”>
<xsd:sequence>
<xsd:element name=”Name” nillable=”false” type=”xsd:string”/>
<xsd:element name=”ID” minOccurs=”0” nillable=”true” type=”xsd:integer”/>
</xsd:sequence>
</xsd:complexType>
WSDLファイルをインポートすると、次の図に示すように、WSDLファイルで定義されたNULL可能および必須のフィールド要素がプロセスオブジェクトにプロパゲートされます。
同様に、次のサンプルに示すように、Swagger JSONファイルでも、必須およびNULL可能なフィールド要素を設定し、サービスコネクタを作成できます。
"definitions" : {
"Process1-3Request" : {
"type" : "object",
"required" : [ "Test" ],
"properties" : {
"Test" : {
"$ref" : "#/definitions"/ProcessObjectReq"
}
}
},
"ProcessObjectReq" : {
"type" : "object",
"properties" : {
"Name" : {
"type" : "string"
},
"ID" : {
"type" : "integer",
"format" : "int32"
}
},
"required": [
"Name"
],
"x-nullable":["ID"]
}
}
次のサンプルに示すように、OpenAPI 3.0ファイルでも、必須およびNULL可能なフィールド要素を設定し、プロセスオブジェクトを作成できます。
"ApiResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32",
"required": true,
"nullable": false
},
},
...
NULL可能フィールドがあるプロセスオブジェクトをプロセスで使用している場合に、そのプロセスのSwagger JSONファイルを生成しても、生成されたSwagger JSONファイルにはプロセスオブジェクトで定義されたx-nullableフィールドが含まれないことがあります。デフォルトでは、このフィールドはNULL可能ではないものとして設定されます。そのため、NULL可能フィールド値を保持するには、WSDLファイルまたはOpenAPI 3.0ファイルを使用することをお勧めします。
次の図は、インポートされたSwagger JSONファイルからの必須フィールドとNULL可能フィールドが選択されている状態を示しています:
このプロセスオブジェクトをプロセスで使用する場合、必須およびNULL可能としてマークされたフィールドは、生成されたWSDLファイル、Swaggerファイル、およびOpenAPI 3.0ファイルで同じ制限を使用します。
Postmanコレクションからのサービスコネクタの作成
サービスコネクタを作成するには、REST APIの定義済の構造を使用してPostmanコレクションをインポートします。サービスコネクタは、APIの操作およびデータ構造を継承します。
Postmanコレクションからサービスコネクタを作成するには、次の手順を実行します。
- 1アプリケーションの統合で、［新規］ > ［サービスコネクタ］をクリックします。
［新しいアセット］ダイアログボックスが表示されます。次の図は、［新しいアセット］ダイアログボックスを示しています。
- 2［Postmanコレクションからのサービスコネクタ］をクリックしてから、［作成］をクリックします。
［Postmanコレクションからのサービスコネクタ］ページが表示されます。
- 3［PostmanコレクションJSONファイル］タブで、サービスコネクタの次の基本プロパティを定義します。
- 4Nextをクリックします
- Postmanコレクションファイルで定義された操作と説明が、［サービスと操作］タブに表示されます。
次の図は、［サービスと操作］タブを示します。
- 5リストから1つ以上の操作を選択します。
- 6Nextをクリックします
［サマリ］タブが表示されます。
- 7Postmanコレクションをインポートする前に、サービスコネクタ名、場所、サービスURL、プロトコルなどのサービスコネクタ設定を確認してください。
次の図は、［サマリ］タブを示しています。
- 8［インポートの開始］をクリックします。
［進行状況］タブが表示されます。
- このタブの［ステータス］ページには、インポートプロセスのステータスが表示されます。インポート中にエラーが発生すると、ウィザードの［進行状況］タブの［エラー/警告］にエラーが表示されます。エラーに対処した後に、Postmanコレクションファイルを再びインポートできます。
注: インポート処理中にダイアログボックスを閉じた場合、処理は停止し、サービスコネクタは作成されません。
次の図は、［進行状況］タブを示しています。
Postmanコレクションのルールとガイドライン
Postmanコレクションをインポートしてサービスコネクタを作成する場合は、次のルールとガイドラインを考慮してください。
- •ネストされたフォルダ構造にPostmanコレクションが存在し、基本認証を使用している場合、フィールドは作成されません。フィールドは手動で作成する必要があります。
- •Postmanコレクションをインポートしてサービスコネクタを作成する際に、要求名に日本語の文字を使用することはできません。日本語の文字は正しく解析されていません。
- •Postmanコレクションに複数のホスト名を指定することはできません。Postmanコレクションをインポートしてサービスコネクタを作成した後に、異なるホストを持つ新しいアクションをサービスコネクタに追加する必要があります。
- •Postmanコレクションで提供されるクエリパラメータ値は、サービスコネクタの作成時にはインポートされません。ペイロードのキーを持つフィールドのみを作成できます。Postmanコレクションからサービスコネクタを作成した後に、値を手動で入力する必要があります。
- •Postmanコレクションで指定した本文ペイロードは、サービスコネクタにインポートされません。Postmanコレクションからサービスコネクタを作成した後に、本文の値を手動で渡す必要があります。
- •同じホスト名と同じ方法であっても異なるクエリパラメータを持つ複数の要求を作成すると、最後の要求のみがサービスコネクタにインポートされます。Postmanコレクションからサービスコネクタを作成した後に、追加の要求を手動で作成する必要があります。
