検索の追加
検索は、サービスに対してクエリーして、ドロップダウンリストとして表示される値のリストを取得する読み取り専用メカニズムです。検索は、フォームにすでに提供されている情報のその他のアイテムに基づくことができます。検索を使用することで、操作またはトリガーを設定する際、サードパーティアカウントのリソースに関連付けられている値を手動で入力したり覚えておいたりする必要がなくなります。
検索は操作とトリガーで使用します。検索で多数のアイテムを表示するには、ページングメカニズムが使用されます。
検索は初期データフィルタをサポートしています。たとえば、検索フィールドにテキストを入力して矢印をクリックすると、そのテキストを含む値のリストが表示されます。
その他の成果物とは異なり、検索に外部のバージョンは付きません。検索の各呼び出しは検索成果物での関数です。この結果、1 つのコネクタは検索成果物を 1 つだけ持ちます。
たとえば、以下の図では検索操作が使用されています。この検索はユーザーの電子メールを Gmail からフェッチし、これらの値が「メッセージ ID」に入力として表示されます。これが可能であるのは、このフィールドに検索を使用可能であることがスキーマによって指定されているためです。
「メール詳細を取得」操作を実装するには、電子メールアカウントの ID が必要です。検索スクリプトはユーザーの Gmail アカウントの認証を使用して、ユーザーのアカウントですべての電子メールをサーチします。操作フォームにリストが表示され、ユーザーは適切な ID を検索として選択できます。
新規検索を作成するには、次の手順に従います。
1. コマンドプロンプトから、次のコマンドを実行します。
a. cd <user project root directory>
b. flow add lookup
検索の名前はコネクタの名前であり、検索はプロジェクトディレクトリ内の検索フォルダに作成されます。
このコマンドでは次のオプションを使用できます。
オプション | 説明 | データ型 |
|---|---|---|
--version | バージョン番号を表示します。 | [ブール] |
--help | ヘルプを表示します | [ブール] |
--parentDir, -d | プロジェクトの親ディレクトリ。 | [デフォルト: "."] |
--logLevel, -1 | ログレベルを設定します。 | [デフォルト: "info"] |
2. index.js ファイルで各プロパティを更新します。
検索 JavaScript は単一の JavaScript オブジェクトをエクスポートする必要があります。このオブジェクトにはメソッドをいくつでも含めることができます。index.js ファイルの構造は次のとおりです。
function(input, options, output){
return}
return}
 | 外部サービスが OAuth の代わりに接続を使用する場合、コードが異なる可能性があります。 |
options オブジェクトには、検索で使用するために必要な多くのユーティリティメソッドが用意されています。
validateDependencies(input.<property name>) - 指定したプロパティが入力に含まれていることを確認します。
options.getAccessToken(input.auth, function(err, data) { }): Fetch the access token from the server. input.auth contains a UID that is used to fetch the access token. options.getConnection(input.connection, function(err, data){ }) : Fetch the connection corresponding to the UID contained in the connection property.
検索で使用可能な API 用の SDK については、
ThingWorx Flow コネクタ SDKのセクションを参照してください。
以下の表で、引数の使用方法について説明します。
引数 | 使用方法 |
|---|---|
input | 検索で設定されている依存が含まれています。 |
options | 認証メカニズム、接続またはアクセストークンをフェッチしてページングサポートを有効にするユーティリティメソッドを提供します。 |
output | ThingWorx Flow に結果を返すために呼び出す必要があるコールバック。これはノードのエラーファースト規則に従います。 この結果は JSON オブジェクトの配列でなければなりません。通常は、ID と値のペアになります。動的スキーマが追加された場合、フィールドがさらに追加されることがあります。詳細については、「スキーマの動的注入」のセクションを参照してください。 結果をコールバック (出力関数) に渡す必要があり、これは ID と値を含む JSON オブジェクトの配列でなければなりません。 結果のフォーマットは以下のようになります。 { [ {"id":"id1","value":"value1"}, {"id":"id2","value":"value2"}, ], “next_page”: true } |
スキーマの動的注入
ある操作の入力/出力スキーマが固定されている場合、機能が豊富な操作を構築する際に制限が生じます。操作の入力/出力スキーマは、検索をロードするときや、検索から値を選択するときに、ユーザーの選択に基づいて更新できます。その結果、更新された入力スキーマと一致するようにフォームが更新されて現在の値が維持されます。さらに、次の操作でマッピング可能な出力フィールドが、更新された出力スキーマと一致するように更新されます。
ある操作の入力/出力スキーマに対する更新は、検索結果処理インタフェースで行えます。
検索結果を返すときに動的スキーマを注入したり、(選択したオプションの) onSelect 属性を介して検索に別の関数を追加したりできます。検索のロード時に注入する場合、動的スキーマ注入には検索のすべての値のスキーマが必要です。
| | 一部の Thing では、連続する 2 つの検索を使用した複数レベルの注入が可能です。複数レベルの注入は制限付きで追加できますが、除去できません。 |
フォームが表示する入力スキーマを追加する方法としては、検索の結果 JSON で、ID と value の横の schema、parent、append 属性を使用します。同様に、出力スキーマを追加するには、outSchema、outAppend、outParent を使用します。これは接続している操作が開いたときに操作の出力スキーマとして表示されます。通常は、ここで提供されるスキーマが指定された親に追加されてプロパティが拡張される場合、append または outAppend と parent または outParent が一緒に使用されます。append が使用されていない場合、そのスキーマが新しく追加したスキーマに置き換えられます。
parent または outParent 属性は、各スキーマの (object タイプの) スキーマエレメントの ID です。parent または outParent 属性がない場合、更新のデフォルトのコンテキストは各スキーマのルートになります。注入スキーマで提供されるプロパティを既存のプロパティとマージするか append/outAppend がない場合には置き換えることによって、parent または outParent オブジェクトの範囲内でスキーマの更新が行われます。
注入される出力スキーマで userSelected 属性を使用することもできます。これは、フォームでオプションを選択したときに、値が false の場合はデフォルトスキーマを注入し、値が true の場合はこれをサブセットに置き換えるときに使用されます。フォームの配列エレメントが削除されたときにすべての userSelected = true 属性が除去された場合、そのスキーマはデフォルト値に戻ります。
たとえば、OData コネクタの場合、以下の図に示す入力と出力の注入スキーマを設定します。
OData の入力注入スキーマは次のとおりです。
"schema": {
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
OData の出力注入スキーマは次のとおりです。
"outSchema": {
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
上記の例に示されているように、プロパティ visible = true を設定することによって、動的に注入された出力スキーマのマッピングユーザーインタフェースでいくつかのパラメータを修正できます。
入力と出力の動的スキーマを国際化するには、
コネクタでのインターナショナリゼーションのサポートのセクションを参照してください。
ページング
検索はページングをサポートしており、結果の多くのページを生成することができます。すべての呼び出しは、結果の単一のページを生成します。UI では、リストの "結果をさらにロード" をクリックしてページを取得できます。input および options オブジェクトには、ページングを処理するメソッドとプロパティが含まれています。
• options.getNextPage(boolean) - ページング内で使用し、URL を返して次のページをフェッチします。この URL は、ページングが正常に動作するために、結果オブジェクトの "next_page" プロパティ上に設定する必要があります。これ以上ページが返されないようにする場合は、このプロパティを false に設定します。
• options.maxResults - 一度に返される結果の最大数を取得するために、ページングで使用されます。
• input.page - 現在のページ番号。
• input.searchById - ID でサーチします。
• input.searchByValue - 値でサーチします。
ID および値によるサーチは、検索でサーチ可能フラグが true に設定されている場合に使用できます。検索の例については、上記のセクションを参照してください。これらのプロパティは、ターゲットシステムで ID または値に一致するアイテムをサーチすることによってサーチを絞り込む際に役立ちます。
| | ID と値は、ターゲットシステムの異なるフィールドを参照することができます。 |