レコードの検索
FRS HEAT 統合 Web サービスは、特定のテナント内のレコードを検索するためのいくつかの手段を提供します。 次の表は、レコードの検索を可能にする 4 つの Web メソッドをまとめたものです。
ウェブメソッド | 適用範囲 |
|---|---|
検索 | 任意のクエリ基準を使用してレコードを検索するための汎用メソッド。 以下で説明する他の 3 つの便利な Web メソッドを使用して目的のクエリ条件を表現できない場合は、この Web メソッドを使用します。 |
ビジネスオブジェクトの検索 | データベース内の RecId フィールド値を使用して、ビジネス オブジェクト レコードを検索します。 レコードはRecId(つまり 主キーの場合、指定された RecId がビジネス オブジェクト内の既存のレコードの 1 つと一致すると仮定して、この Web メソッドは 1 つのレコードだけを返します。 検索するレコードの RecId がすぐに利用できない場合は、代わりに他の WebMethods を使用する必要があります。 |
フィールドによる単一ビジネスオブジェクトの検索 | 指定されたフィールド/値の基準を使用してビジネス オブジェクト レコードを検索し、見つかった場合は完全に一致するレコードを返します。 たとえば、この Web メソッドは、LoginId フィールドまたは PrimaryEmail フィールドのいずれかを使用して Profile.Employee レコードを識別するために使用できます (列のフィールド値がデータベース テーブル内で一意であると想定)。 名前が示すように、この Web メソッドは、一致するレコードが見つかった場合に、正確に 1 つのレコードを返します。 検索で複数のレコードが返される場合は、結果が返されないことに注意してください。 複数の結果が返されるかどうか不明な場合は、代わりに FindMultipleBusinessObjectsByField または FindBusinessObject Web メソッドのいずれかを使用します。 |
フィールド別に複数のビジネスオブジェクトを検索 | 指定されたフィールド/値の条件を使用してビジネス オブジェクト レコードを検索し、すべての結果を配列で返します。 たとえば、この Web メソッドを使用すると、ステータスが「解決済み」のすべてのインシデント レコードを識別できます。 名前が示すように、この Web メソッドは配列を介して 1 つ以上の一致する結果を返します。 検索条件によって 1 つのレコードが返されることが事前にわかっている場合は、FindSingleBusinessObjectByField Web メソッドを使用すると、レコードに直接アクセスするより便利な方法が提供されます。 それ以外の場合でも、FindMultipleBusinessObjecsByFieldWebMethod は使用可能であり、配列の最初の項目を介してレコードを取得できます。 |
上記の表から、 FindBusinessObject、 FindSingleBusinessObjectByField、および FindMultipleBusinessObjectsByField Web メソッドはすべて Search Web メソッドの特殊なケースであることがわかります。後者の Web メソッドは、任意の複雑なクエリを表現するために使用できます。
次のセクションでは、4 つのクエリ Web メソッドについて詳しく説明します。
ビジネスオブジェクトの検索
プライマリ識別子(データベースのRecIdフィールド)を使用して単一のビジネスオブジェクトを取得します。
リクエスト構文:
FRSHEATIntegrationFindBOResponse FindBusinessObject(string sessionKey, string tenantId, string boType, string recId)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- boType: 取得するビジネス オブジェクトのタイプ (例: Incident または Change)。
- recId: オブジェクトの一意の識別子
戻り値:
次のように定義される FRSHEATIntegrationFindBOResponse オブジェクト:
public class FRSHEATIntegrationFindBOResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
public WebServiceBusinessObject obj { get; set; }
}
FRSHEATIntegrationFindBOResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – Connect WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
- obj – FindBusinessObject WebMethod呼び出しで正確なレコードが見つかる場合(つまり、 ステータスフィールドの値が「成功」の場合、ビジネスオブジェクトレコードはこのフィールドを介してアクセスできます。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態 | 説明 |
|---|---|
成功 | ビジネス オブジェクトは正常に見つかりました。応答オブジェクトの obj フィールドを介してレコードにアクセスします。 |
エラー | ビジネス オブジェクトが正常に見つからない場合、obj フィールドは null になり、例外は exceptionReason フィールドに格納されます。 最も一般的なエラーは、指定されたビジネス オブジェクトがテナント内に存在しない場合に発生する「テーブルが見つからない」例外です。 ビジネスオブジェクトの名前が正しく入力されているか再度確認してください(例: 「インシデント」、「プロファイル.従業員」など) |
見つかりません | 指定されたビジネス オブジェクトはテナント内に存在しますが、指定された RecID 値はオブジェクト内の既存のレコードのいずれとも一致しません。 これは例外的な条件ではないため、exceptionReason フィールドに例外は保存されず、obj フィールドは null になります。 目的のレコードの RecID フィールドがテナント内に実際に存在するかどうかを再確認してください。 代替クエリWebメソッド(例: レコードを取得するには、代わりに「FindSingleBusinessObjectByField」を使用することもできます。 |
例
FRSHEATIntegrationFindBOResponse res = frSvc.FindBusinessObject(authSessionKey, tenantId, "Incident", "A981FBEBAA8B4EE2820364505855ABC2");
if (res.status == "Success")
{
foreach (WebServiceFieldValue f in res.obj.FieldValues)
{
if (string.Compare(f.Name, "LastModDateTime", true) == 0)
{
日付時刻 lastMod;
if (f.Value != null)
{
lastMod = (DateTime)f.Value;
Console.WriteLine("The LastModDateTime of the record is " + lastMod.ToString());
}
}
}
}
フィールドによる単一ビジネスオブジェクトの検索
この Web メソッドは、指定されたフィールド/値の基準を使用して、単一のビジネス オブジェクトを取得します。
これは、一意のフィールドを使用して一致するレコードを検索するために導入された便利な Web メソッドです。
このクエリ Web メソッドが役立つ一般的な使用例をいくつか示します。
- LoginIDフィールドを使用して、特定のProfile.Employeeレコードを検索します。
- PrimaryEmailフィールドを使用して、特定のProfile.Employeeレコードを検索します。
- チームフィールドを使用して特定のStandardUserTeamレコードを検索します。
- 名前フィールドを使用して特定の組織単位レコードを検索します
リクエスト構文:
FRSHEATIntegrationFindBOResponse FindSingleBusinessObjectByField(string sessionKey, string tenantId, string boType, string fieldName, string fieldValue)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- boType: 取得するビジネス オブジェクトのタイプ (例: Incident または Change)。
- recId: オブジェクトの一意の識別子
- fieldName: 検索対象となるビジネスオブジェクト内のフィールドの名前(例: "状態")
- fieldValue: 一致するレコードで検索するフィールドの値(例: "アクティブ")
戻り値:
次のように定義される FRSHEATIntegrationFindBOResponse オブジェクト:
public class FRSHEATIntegrationFindBOResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
public WebServiceBusinessObject obj { get; set; }
}
FRSHEATIntegrationFindBOResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – Connect WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
- obj – FindBusinessObject WebMethod呼び出しで正確なレコードが見つかる場合(つまり、 ステータスフィールドの値が「成功」の場合、ビジネスオブジェクトレコードはこのフィールドを介してアクセスできます。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態 | 説明 |
|---|---|
成功 | ビジネス オブジェクトは正常に見つかりました。応答オブジェクトの obj フィールドを介してレコードにアクセスします。 |
エラー | ビジネス オブジェクトが正常に見つからない場合、obj フィールドは null になり、例外は exceptionReason フィールドに格納されます。 典型的なエラーの 1 つは、指定されたビジネス オブジェクトがテナント内に存在しない場合に発生する、テーブルが見つからない例外です。 ビジネスオブジェクトの名前が正しく入力されているか再度確認してください(例: 「インシデント」、「プロファイル.従業員」など) 他によく発生するエラーは、ビジネス オブジェクトに指定されたフィールドが存在しない場合に発生します。この場合、エラー メッセージの形式は次のようになります。 ObjectTableMap: フィールド <FieldName> がテーブル <Business Object>に見つかりません フィールド名が正しく入力されていること、および特定のビジネス オブジェクトに対して実際に定義されていることを再確認してください。 |
見つかりません | 指定されたビジネス オブジェクトはテナント内に存在しますが、指定された RecID 値はオブジェクト内の既存のレコードのいずれとも一致しません。 これは例外的な条件ではないため、exceptionReason フィールドに例外は保存されず、obj フィールドは null になります。 目的のレコードの fieldValue フィールドがテナント内に実際に存在するかどうかを再確認してください。 代替クエリWebメソッド(例: レコードを取得するには、「FindSingleBusinessObjectByField」などのメソッドが使用される場合があります。 |
複数の結果 | 指定された検索条件により、一致する結果が複数返されました。 この Web メソッドの目的は、一致するビジネス オブジェクトを 1 つ返すことなので、応答オブジェクトのステータスが「MultipleResults」の場合は、応答オブジェクトの obj フィールドは null のままになります。 複数の一致する結果が返される可能性がある場合は、代わりに「FindSingleBusinessObjectByField」Web メソッドを使用する必要があります。 |
例
FRSHEATIntegrationFindBOResponse res = frSvc.FindSingleBusinessObjectByField(authSessionKey, tenantId, "Incident", "IncidentNumber", "10001");
if (res.status == "Success")
{
foreach (WebServiceFieldValue f in res.obj.FieldValues)
{
if (string.Compare(f.Name, "LastModDateTime", true) == 0)
{
日付時刻 lastMod;
if (f.Value != null)
{
lastMod = (DateTime)f.Value;
Console.WriteLine("The LastModDateTime of the record is " + lastMod.ToString());
}
}
}
}
フィールド別に複数のビジネスオブジェクトを検索
この Web メソッドは、指定されたフィールド/値の条件を使用して 1 つ以上のビジネス オブジェクトを取得し、その結果をビジネス オブジェクトの配列として返します。
たとえば、この Web メソッドを使用すると、ステータスが「アクティブ」のすべてのインシデント レコード、タイプが「メジャー」のすべての変更などを取得できます。
この Web メソッドでは、単一のフィールド/値の基準に基づいた検索のみが可能です。より複雑なクエリを表現する必要がある場合は、代わりに検索 Web メソッドを使用する必要があります。
また、この Web メソッドは、一致するレコードが 1 つだけ返される場合でも、常に結果を配列で返します。 その場合、必要なクエリ条件によって 1 つのレコードが返されるのであれば、FindSingleBusinessObjectByField Web メソッドを使用する方が便利かもしれません。
リクエスト構文:
FRSHEATIntegrationSearchResponse FindMultipleBusinessObjectsByField(string sessionKey, string tenantId, string boType, string fieldName, string fieldValue)パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- boType: 取得するビジネス オブジェクトのタイプ (例: Incident または Change)。
- recId: オブジェクトの一意の識別子
- fieldName: 検索対象となるビジネスオブジェクト内のフィールドの名前(例: "状態")
- fieldValue: 一致するレコードを検索するフィールドの値(例: "アクティブ")
戻り値:
次のように定義される FRSHEATIntegrationSearchResponse オブジェクト:
public class FRSHEATIntegrationSearchResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
パブリック リスト<List<WebServiceBusinessObject>> objList { get; set; }
}
FRSHEATIntegrationSearchResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – Connect WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
- objList – WebMethod呼び出しで1つ以上のレコードが見つかった場合(つまり、 ステータス フィールドの値が「成功」の場合、結果はこのフィールド (WebServiceBusinessObject オブジェクトのリストのリスト) を介して返されます。 検索条件が複数のオブジェクトに一致した場合、外部リストには複数のビジネス オブジェクトが含まれます。 検索条件が結合を要求した場合、内部リストには結合されたビジネス オブジェクトが含まれます。 SQL 応答フィールドとは異なり、結合された各オブジェクトは個別のリストに保持され、混ざり合うことはありません。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態 | 説明 |
|---|---|
成功 | ビジネス オブジェクトは正常に見つかります。応答オブジェクトの objList フィールドを介して一致するレコードにアクセスすると、結果が WebServiceBusinessObjects のリストのリストとして返されます。 |
エラー | ビジネス オブジェクトが正常に見つからない場合、objList フィールドは null になり、例外は exceptionReason フィールドに格納されます。 典型的なエラーの 1 つは、指定されたビジネス オブジェクトがテナント内に存在しない場合に発生する、テーブルが見つからない例外です。 ビジネスオブジェクトの名前が正しく入力されているか再度確認してください(例: 「インシデント」、「プロファイル.従業員」など) 他によく発生するエラーは、ビジネス オブジェクトに指定されたフィールドが存在しない場合に発生します。この場合、エラー メッセージの形式は次のようになります。 ObjectTableMap: フィールド <FieldName> がテーブル <Business Object>に見つかりません フィールド名が正しく入力されていること、および特定のビジネス オブジェクトに対して実際に定義されていることを再確認してください。 |
見つかりません | 指定されたビジネス オブジェクトはテナント内に存在しますが、指定された RecID 値はオブジェクト内の既存のレコードのいずれとも一致しません。 これは例外的な条件ではないため、exceptionReason フィールドに例外は保存されず、objList フィールドは null になります。 目的のレコードの fieldValue が実際にテナント内に存在するかどうかを再確認してください。 |
例
FRSHEATIntegrationSearchResponse res = frSvc.FindMultipleBusinessObjectsByField(authSessionKey, tenantId, "Incident", "Status", "Active");
if (res.status == "Success")
{
WebServiceBusinessObject[][] incidentList = res.objList;
foreach (WebServiceBusinessObject[]incidentOuterList inincidentList)
{
foreach (incidentOuterList 内の WebServiceBusinessObject インシデント)
{
WebServiceFieldValue[] incidentFieldList = incident.FieldValues;
WebServiceFieldValue incidentNumberField = incidentFieldList.SingleOrDefault(f => f.Name == "IncidentNumber");
Console.WriteLine("インシデント は選択基準に一致します",incidentNumberField.Value);
}
}
}
検索
この Web メソッドは、検索条件を満たす 1 つ以上のビジネス オブジェクトを取得します。 これは SQL スタイルのクエリです。
前の 3 つのクエリ Web メソッドと比較すると、これは任意の複雑なクエリを表現するために使用できる汎用 Web メソッドです。
リクエスト構文:
FRSHEATIntegrationSearchResponse Search(string sessionKey, string tenantId, ObjectQueryDefinition query)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- クエリ: 検索条件を記述する構造。 これは、SQL SELECT リクエストの構造に従い、TOP、WHERE、JOIN、ORDER BY 句を含む SELECT クエリで可能なパラメータのほとんどをキャプチャします。
戻り値:
次のように定義される FRSHEATIntegrationSearchResponse オブジェクト:
public class FRSHEATIntegrationSearchResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
パブリック リスト<List<WebServiceBusinessObject>> objList { get; set; }
}
FRSHEATIntegrationSearchResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – Connect WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
- objList – WebMethod呼び出しで1つ以上のレコードが見つかった場合(つまり、 ステータス フィールドの値が「成功」の場合、結果はこのフィールド (WebServiceBusinessObject オブジェクトのリストのリスト) を介して返されます。 検索条件が複数のオブジェクトに一致した場合、外部リストには複数のビジネス オブジェクトが含まれます。 検索条件が結合を要求した場合、内部リストには結合されたビジネス オブジェクトが含まれます。 SQL 応答フィールドとは異なり、結合された各オブジェクトは個別のリストに保持され、混ざり合うことはありません。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態 | 説明 |
|---|---|
成功 | ビジネス オブジェクトは正常に見つかります。応答オブジェクトの objList フィールドを介して一致するレコードにアクセスすると、結果が WebServiceBusinessObjects のリストのリストとして返されます。 |
エラー | ビジネス オブジェクトが正常に見つからない場合、objList フィールドは null になり、例外は exceptionReason フィールドに格納されます。 典型的なエラーの 1 つは、指定されたビジネス オブジェクトがテナント内に存在しない場合に発生する、テーブルが見つからない例外です。 ビジネスオブジェクトの名前が正しく入力されているか再度確認してください(例: 「インシデント」、「プロファイル.従業員」など) 他によく発生するエラーは、ビジネス オブジェクトに指定されたフィールドが存在しない場合に発生します。この場合、エラー メッセージの形式は次のようになります。 ObjectTableMap: フィールド <FieldName> がテーブル <Business Object>に見つかりません フィールド名が正しく入力されていること、および特定のビジネス オブジェクトに対して実際に定義されていることを再確認してください。 |
見つかりません | 指定されたビジネス オブジェクトはテナント内に存在しますが、指定された RecID 値はオブジェクト内の既存のレコードのいずれとも一致しません。 これは例外的な条件ではないため、exceptionReason フィールドに例外は保存されず、objList フィールドは null になります。 目的のレコードの fieldValue が実際にテナント内に存在するかどうかを再確認してください。 |
例:
次の例では、優先度が 1 で、ステータスが「アクティブ」であるインシデント レコードを検索し、一致する結果から対応する IncidentNumber 値を取得します。
ObjectQueryDefinition query = new ObjectQueryDefinition();
クエリー.Select = 新しい SelectClass();
// IncidentからIncidentNumberフィールドの値のみを取得します。
// 検索を呼び出すとき
FieldClass[] incidentFieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
}
};
クエリー.Select.Fields = インシデントフィールドオブジェクト;
クエリ.From = 新しい FromClass();
query.From.Object = "インシデント";
query.Where = 新しいルールクラス[] {
new RuleClass()
{
結合 = "AND"、
Condition = "=",
フィールド = "優先度"、
値 = "1"
},
新しいルールクラス()
{
結合 = "AND"、
Condition = "=",
フィールド = "ステータス"、
値 = "アクティブ"
}
};
FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, query);
if (searchResponse.status == "Success")
{
WebServiceBusinessObject[][] incidentList = searchResponse.objList;
foreach (WebServiceBusinessObject[]incidentOuterList inincidentList)
{
foreach (WebServiceBusinessObject incident in incidentOuterList)
{
// 選択基準の1つのフィールドだけを取得するので
// (つまり IncidentNumber)に対応します。
// 結果を取得するときのincident.FieldValues[0].Value
Console.WriteLine("インシデント は選択基準に一致します",incident.FieldValues[0].Value);
}
}
}
