検索結果の理解
前述のように、検索Webメソッドの戻り値はWebServiceBusinessobjectオブジェクトのリストのリストです(つまり、 2次元配列)。
前のセクションでは、単一のビジネスオブジェクト(例: "インシデント")。
現在のオブジェクトと関連オブジェクトに対して検索を実行する場合、2 次元配列内の各項目が一致する親と子の組み合わせを表すことに注意することが重要です。
検索結果の形式を理解する最善の方法は、上記の点を念頭に置いて、次の 4 つの検索シナリオを検討することです。
シナリオ1: 単一のビジネスオブジェクトに対して検索を実行し、完全一致を返す
検索が単一のビジネスオブジェクトに対して定義されていると仮定します(例: 「インシデント」と入力すると、検索結果には 1 件の正確なレコードが返されます。
ここで、 objList[0][0] には一致するインシデントレコードが含まれています。
次のコードサンプルを検討してください。
ObjectQueryDefinition query = new ObjectQueryDefinition();
FieldClass[] fieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "ステータス"、
タイプ = "テキスト"
}
};
query.Select = new SelectClass();
query.Select.Fields = fieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.Where = new RuleClass[] {
新しいルールクラス()
{
フィールド = "IncidentNumber"、
条件 = "="、
値 = "10001"
}
};
FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, query);
if (searchResponse.status == "Success")
{
WebServiceBusinessObject[][] objList = searchResponse.objList;
foreach (WebServiceBusinessObject[] objOuterList in objList)
{
foreach (WebServiceBusinessObject obj in objOuterList)
{
WebServiceFieldValue[] objFieldList = obj.FieldValues;
Console.WriteLine(" と \\"\\" が選択条件に一致します", obj.BusinessObjectName, objFieldList[0].Name, objFieldList[0].Value);
}
}
}
}
ここでは、テナント内のインシデント 10001 を具体的に検索しています。 レコードがテナント内に存在すると仮定すると、objList[0][0]を介して利用できるようになります。

シナリオ2: 単一のビジネスオブジェクトに対して検索を実行し、複数の一致が返される
検索が単一のビジネスオブジェクトに対して定義されていると仮定します(例: 「インシデント」と入力すると、検索結果には n 件の一致するレコードが返されます。
この場合、一致するレコードにはobjList[0][0]からobjList[n-1][0]を通じてアクセスできます。
たとえば、検索で10件のインシデントレコードが返されるとします。インシデントレコードにはobjList[0][0]からobjList[9][0]を通じてアクセスできます。
ここでは、2 次元配列の最初のインデックスは変更されますが、2 番目のインデックスは 0 のままです。
次のコードサンプルを検討してください。
ObjectQueryDefinition query = new ObjectQueryDefinition();
FieldClass[] fieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "ステータス"、
タイプ = "テキスト"
}
};
query.Select = new SelectClass();
query.Select.Fields = fieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.Where = new RuleClass[] {
新しいルールクラス()
{
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
}
};
query.OrderBy = new OrderByClass[] {
新しい OrderByClass()
{
名前 = "インシデント番号",
方向 = "ASC"
}
};
FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, query);
if (searchResponse.status == "Success")
{
WebServiceBusinessObject[][] objList = searchResponse.objList;
foreach (WebServiceBusinessObject[] objOuterList in objList)
{
foreach (WebServiceBusinessObject obj in objOuterList)
{
WebServiceFieldValue[] objFieldList = obj.FieldValues;
Console.WriteLine(" と \\"\\" が選択条件に一致します", obj.BusinessObjectName, objFieldList[0].Name, objFieldList[0].Value);
}
}
}
}
シナリオ 1 のコードと比較すると、次の部分のみが更新されています。
query.Where = new RuleClass[] {
新しいルールクラス()
{
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
}
};
ここでは、IncidentNumber が 10010 以下のインシデント レコードを検索しています。
テナントに 10001 から 10010 までのインシデント レコードがあると仮定すると、インシデント 10001 には objList[0][0] を介してアクセスでき、インシデント 10002 には objList[1][0] を介してアクセスでき、インシデント 10010 には objList[9][0] を介してアクセスできます。
次の図は、検索結果の 2 次元配列を介して、コレクション内の各項目に個別にアクセスする方法を示しています。
検索対象となる子オブジェクトがないため、objList[n][0]を使用してすべての項目にアクセスできます。

シナリオ3: 単一のビジネスオブジェクトとそれに関連する子オブジェクトに対して検索を実行し、親オブジェクトに完全一致するものを1つ返す
Journal.Email レコードと一致するインシデントを検索していると仮定します。
検索によって、一致する Incident レコードが 1 つ返され、その中に 4 つの関連する Journal.Email レコードが含まれているとします。
現在のオブジェクトと関連オブジェクトに対して検索を実行する場合、2 次元配列内の各項目が一致する親と子の組み合わせを表すことに注意することが重要です。
このシナリオでは、一致する親 Incident レコードが 1 つしかないため、検索結果には、一致する Journal.Email レコードごとに 1 つずつ、同じ親レコードが 4 回含まれます。
したがって、親インシデントレコードには、objList[0][0]、objList[1][0]、objList[2][0]、またはobjList[3][0]のいずれかを使用してアクセスできます。 ここで、最初のインデックス値は変化し、2 番目のインデックス値は 0 になります (メイン オブジェクトを示すため)。
一致する個々のJournal.Email子レコードには、objList[0][1]、objList[1][1]、objList[2][1]、およびobjList[3][1]を使用してアクセスできます。 ここで、最初のインデックス値は変化します (一致する各 Journal.Email レコードに対応するため)。また、2 番目のインデックスは 1 になります (最初の子オブジェクトを示すため)。
次のコードサンプルを検討してください。
ObjectQueryDefinition query = new ObjectQueryDefinition();
FieldClass[] fieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "Journal.Subject",
タイプ = "テキスト"
}
};
query.Select = new SelectClass();
query.Select.Fields = fieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.From.Links = new FromLinkClass[] {
new FromLinkClass {
関係 = "",
オブジェクト = "ジャーナル
}
};
query.Where = new RuleClass[] {
新しいルールクラス()
{
フィールド = "IncidentNumber"、
条件 = "="、
値 = "10001"
},
新しいルールクラス()
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "受信メール"
},
};
query.OrderBy = new OrderByClass[] {
新しい OrderByClass()
{
名前 = "インシデント番号",
方向 = "ASC"
},
新しい OrderByClass()
{
名前 = "Journal.Subject",
方向 = "ASC"
}
};
FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, query);
if (searchResponse.status == "Success")
{
WebServiceBusinessObject[][] objList = searchResponse.objList;
foreach (WebServiceBusinessObject[] objOuterList in objList)
{
foreach (WebServiceBusinessObject obj in objOuterList)
{
WebServiceFieldValue[] objFieldList = obj.FieldValues;
Console.WriteLine(" と が選択条件に一致します", obj.BusinessObjectName, objFieldList[0].Name, objFieldList[0].Value);
}
}
}
ここでは、IncidentNumberが10001で、Categoryが「受信メール」であるJournal.Emailレコードが関連付けられているインシデントレコードを検索しています(つまり、 電子メール リスナー経由でインシデント レコードに添付された電子メール)。
検索ではトップレベルのオブジェクト(つまり 「Incident」だけでなく、関連する「Journal.Email」レコードも追加するには、追加のコード行を記述する必要があります。
まず、FromLinkClass を指定する必要があります。
query.From.Links = new FromLinkClass[] {
new FromLinkClass {
関係 = "",
オブジェクト = "ジャーナル
}
};
ここでは、Incident から Journal.Email への関係を指定する FromLinkClass の新しいインスタンスを作成します。
既存の「IncidentContainsJournal」関係(ジャーナル ベース オブジェクトを指す)を使用して、インシデントを子ジャーナル レコードに関連付けることができます。
リレーションシップには内部参照名パラメータに指定された値がないため、上記の Relation メンバーの Relation 値は空の文字列のままになります。
検索対象となる実際のオブジェクト (この場合は Journal.Email) は、上記の Object メンバーで指定する必要があります。
FromClass に Links プロパティを指定すると、関連するビジネス オブジェクトのフィールドにアクセスできます。 たとえば、インシデントの IncidentNumber フィールドにアクセスするだけでなく、Journal.Email の Subject にもアクセスできます。
FieldClass[] fieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "Journal.Subject",
タイプ = "テキスト"
}
};
Journal.Email ビジネス オブジェクトの Subject フィールドを参照するには、フィールド名を「Journal.Subject」として指定する必要があることに注意してください。
同様に、Journal.Emailビジネスオブジェクトのフィールドを使用してルール条件を指定するには(例: 「Category」の場合、フィールド名は「Journal.Category」と指定する必要があります。
query.Where = new RuleClass[] {
新しいルールクラス()
{
フィールド = "IncidentNumber"、
条件 = "="、
値 = "10001"
},
新しいルールクラス()
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "受信メール"
},
};
したがって、この例のシナリオでは、テナントにインシデント 10001 が存在し、それに 4 つの Journal.Email が添付されており、件名の値が「Email 1」、「Email 2」、「Email 3」、および「Email 4」であると想定します。
上記のサンプル コードを実行すると、コンソール ウィンドウに次の結果が表示されます。
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 1」のJournal.Emailが選択基準に一致します
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 2」のJournal.Emailが選択基準に一致します
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 3」のJournal.Emailが選択基準に一致します
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 4」のJournal.Emailが選択基準に一致します
前のセクションで述べたように、結果は親/子の組み合わせごとに返されます。 4 つの Journal.Email レコードは同じ Incident レコード (インシデント 10001) に関連付けられているため、この同じ Incident レコードは、関連付けられている Journal.Email 子レコードごとに 1 回ずつ、合計 4 回表示されます。
次の図は、検索結果の 2 次元配列を介して、親/子の組み合わせ内の各項目に個別にアクセスする方法を示しています。

シナリオ4: 単一のビジネスオブジェクトとそれに関連する子オブジェクトに対して検索を実行し、親オブジェクトに一致する複数のオブジェクトを返す
Journal.Email レコードと一致するインシデントを検索していると仮定します。
検索で2つの一致するインシデントレコードが返され、その中には6つの関連するJournal.Emailレコード(最初のインシデントレコードには4つ(例: インシデント10001)、2番目のインシデントレコード(例: インシデント番号10008)。
以前と同様に、現在のオブジェクトと関連オブジェクトに対して検索を実行するときは、2 次元配列内の各項目が一致する親と子の組み合わせを表すことに注意することが重要です。
このシナリオでは、一致する親 Incident レコードが 2 つあり、関連する Journal.Email レコードが 6 つあるため、検索結果には 6 つの結果が返されます。
最初のインシデントレコードは、objList[0][0]、objList[1][0]、objList[2][0]、およびobjList[3][0]のいずれかを使用して表示され、それに対応するJournal.EmailレコードはobjList[0][1]、objList[1][1]、objList[2][1]、およびobjList[3][1]を介して表示されます。
2番目のインシデントレコードはobjList[4][0]とobjList[5][0]のいずれかを使用して表示され、それに対応するJournal.EmailレコードはobjList[4][1]とobjList[5][1]を介して表示されます。
次のコードサンプルを検討してください。
ObjectQueryDefinition query = new ObjectQueryDefinition();
FieldClass[] fieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "Journal.Subject",
タイプ = "テキスト"
}
};
query.Select = new SelectClass();
query.Select.Fields = fieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.From.Links = new FromLinkClass[] {
new FromLinkClass {
関係 = "",
オブジェクト = "ジャーナル
}
};
query.Where = new RuleClass[] {
新しいルールクラス()
{
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
},
新しいルールクラス()
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "受信メール"
},
};
query.OrderBy = new OrderByClass[] {
新しい OrderByClass()
{
名前 = "インシデント番号",
方向 = "ASC"
},
新しい OrderByClass()
{
名前 = "Journal.Subject",
方向 = "ASC"
}
};
FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, query);
if (searchResponse.status == "Success")
{
WebServiceBusinessObject[][] objList = searchResponse.objList;
foreach (WebServiceBusinessObject[] objOuterList in objList)
{
foreach (WebServiceBusinessObject obj in objOuterList)
{
WebServiceFieldValue[] objFieldList = obj.FieldValues;
Console.WriteLine(" と が選択条件に一致します", obj.BusinessObjectName, objFieldList[0].Name, objFieldList[0].Value);
}
}
}
シナリオ 3 のコードと比較すると、次の部分のみが更新されています。query.Where = new RuleClass[] {
新しいルールクラス()
{
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
}
};
ここでは、IncidentNumberが10010以下で、Categoryが「受信メール」であるJournal.Emailレコードが関連付けられているインシデントレコードを検索しています(つまり、 電子メール リスナー経由でインシデント レコードに添付された電子メール)。
したがって、この例のシナリオでは、テナントにインシデント 10001 が存在し、それに 4 つの Journal.Email が添付されており、件名の値が「Email 1」、「Email 2」、「Email 3」、および「Email 4」であると想定します。
テナント内にインシデント 10008 も存在し、件名の値が「メール 5」と「メール 6」である 2 つの Journal.Email レコードが添付されているとします。
上記のサンプル コードを実行すると、コンソール ウィンドウに次の結果が表示されます。
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 1」のJournal.Emailが選択基準に一致します
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 2」のJournal.Emailが選択基準に一致します
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 3」のJournal.Emailが選択基準に一致します
インシデント番号「10001」のインシデントが選択基準に一致します
Journal.Subject「Email 4」のJournal.Emailが選択基準に一致します
インシデント番号「10008」のインシデントが選択基準に一致します
Journal.Subject「Email 5」のJournal.Emailが選択基準に一致します
インシデント番号「10008」のインシデントが選択基準に一致します
Journal.Subject「Email 6」のJournal.Emailが選択基準に一致します
前のセクションで述べたように、結果は親/子の組み合わせごとに返されます。
インシデント 10001 には 4 つの Journal.Email レコードが関連付けられているため、この同じインシデント レコードは、関連付けられている 4 つの Journal.Email 子レコードごとに 1 回ずつ、計 4 回表示されます。
その後、インシデント 10008 に関連付けられた Journal.Email レコードが 2 つあるため、この同じインシデントは、関連付けられた 2 つの Journal.Email 子レコードごとに 1 回ずつ、計 2 回表示されます。
合計で、このような親/子の組み合わせは 6 つあるため、返されるオブジェクト レコードは 12 個になります (Incident 用に 6 個、個別の Journal.Email レコード用に 6 個)。
次の図は、検索結果の 2 次元配列を介して、親/子の組み合わせ内の各項目に個別にアクセスする方法を示しています。

ルール条件のグループ化
前のセクションでは、現在のビジネスオブジェクト(例: 「インシデント」)とそれに関連する子ビジネスオブジェクト(例: 「Journal.Email」)。
前の例では、次のようなクエリを作成する方法について説明しました。
カテゴリが「受信メール」である関連ジャーナル.メール レコードを含む、インシデント番号が 10010 未満のすべてのインシデント レコードを取得します。
Search WebMethod は、ルール条件のグループ化を通じて検索を表現できるほど柔軟です。
たとえば、Search WebMethod を使用すると、次のようなクエリを表現できます。
関連するJournal.Emailレコードを含む、IncidentNumberが10010未満のすべてのインシデントレコードを取得します。
(ジャーナルメールのカテゴリは「受信メール」です)
または
ジャーナルメールの件名は「緊急リクエスト」です)
上記の検索では、Journal.Emailのカテゴリが「受信メール」の場合(つまり、 メールの件名が「緊急リクエスト」になっているか、またはメール リスナー経由で作成されたか (ジャーナルの件名) が「緊急リクエスト」になっているか (メールのカテゴリが「受信メール」か「送信メール」かに関係なく)。
上記の検索を表現するには、次のコードサンプルを検討してください。
ObjectQueryDefinition query = new ObjectQueryDefinition();
FieldClass[] fieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "Journal.Category",
タイプ = "テキスト"
}
};
query.Select = new SelectClass();
query.Select.Fields = fieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.From.Links = new FromLinkClass[] {
新しいFromLinkClass
{
関係 = "",
オブジェクト = "ジャーナル
}
};
query.Where = new RuleClass[] {
新しいルールクラス
{
結合 = "AND"、
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
},
新しいルールクラス
{
ルール = 新しいルールクラス[] {
新しいルールクラス
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "送信メール"
},
新しいルールクラス
{
結合 = "OR"、
フィールド = "Journal.Subject",
条件 = "="、
値 = 「緊急リクエスト」
}
}
}
};
FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, query);
if (searchResponse.status == "Success")
{
WebServiceBusinessObject[][] objList = searchResponse.objList;
foreach (WebServiceBusinessObject[] objOuterList in objList)
{
foreach (WebServiceBusinessObject obj in objOuterList)
{
WebServiceFieldValue[] objFieldList = obj.FieldValues;
Console.WriteLine(" と \\"\\" が選択条件に一致します", obj.BusinessObjectName, objFieldList[0].Name, objFieldList[0].Value);
}
}
}
このコード サンプルは、前のセクションのサンプルのバリエーションであり、いくつかの重要な違いがあります。
特に、ObjectQueryDefinition オブジェクトの Where プロパティの更新に注意してください。
query.Where = new RuleClass[] {
新しいルールクラス
{
結合 = "AND"、
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
},
新しいルールクラス
{
ルール = 新しいルールクラス[] {
新しいルールクラス
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "送信メール"
},
新しいルールクラス
{
結合 = "OR"、
フィールド = "Journal.Subject",
条件 = "="、
値 = 「緊急リクエスト」
}
}
}
};
トップレベルには 2 つの RuleClass オブジェクトがあります。1 つは、前のセクションで説明したように、IncidentNumber が 10010 以下の Incident レコードを検索する条件を表す式です。
新しいルールクラス
{
結合 = "AND"、
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
},
2 番目の RuleClass は、RuleClass の Rules メンバー変数を設定するためにのみ使用されます。
新しいルールクラス
{
ルール = 新しいルールクラス[] {
...
...
...
}
}
したがって、2 番目の RuleClass 内では、2 つの内部 RuleClass を使用して別の RuleClass 配列がインスタンス化されます。
新しいルールクラス
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "送信メール"
},
新しいルールクラス
{
結合 = "OR"、
フィールド = "Journal.Subject",
条件 = "="、
値 = 「緊急リクエスト」
}
したがって、内部の RuleClass 配列を使用すると、基本的に検索の次の部分を表現できます。
関連するJournal.Emailレコードを取得します。
(ジャーナルメールのカテゴリは「受信メール」です)
または
ジャーナルメールの件名は「緊急リクエスト」です)
次の関連クエリを表現するには:
関連するJournal.Emailレコードを取得します。
(ジャーナルメールのカテゴリは「受信メール」です)
そして
ジャーナルメールの件名は「緊急リクエスト」です)
Join メンバー変数は、次のように「OR」から「AND」に変更する必要があります。
新しいルールクラス
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "送信メール"
},
新しいルールクラス
{
結合 = "AND"、
フィールド = "Journal.Subject",
条件 = "="、
値 = 「緊急リクエスト」
}
上記の例では、RuleClass オブジェクトの Rules メンバー変数を設定することで、ルールをグループ化する方法がわかります。
つまり、RuleClass はコンポジションを使用して、Join プロパティを介して AND または OR 演算子を使用して、RuleClass を任意にグループ化できるようにします。
全文検索
通常のSQLスタイルの検索に加えて、Search WebMethodはビジネスオブジェクト(例: インシデント オブジェクトの全文カタログに対して、「Email Down」という用語を含むレコードを検索します。
RuleClass には ConditionType というメンバーが含まれています。これは SearchConditionType 型で、次の 2 つの許容値を持つ列挙型です。
- ByField - 0 (通常の SQL 検索)
- ByText - 1 (全文SQL検索)
public enum SearchConditionType
{
ByField = 0,
ByText = 1
}
通常の検索は、SearchConditionType を ByField に設定することによって実行されます。これは検索のデフォルト モードであるため、RuleClass のインスタンス化中にこれを明示的に設定する必要はありません。
全文検索を実行するには、RuleClass の ConditionType を ByText に明示的に設定する必要があります。
新しいルールクラス()
{
結合 = "AND"、
条件 = "="、
ConditionType = SearchConditionType.ByText,
値 = "メールダウン"
}
特に、Field メンバー (以前の検索の例に存在していた) が RuleClass で指定されていないことに注意してください。検索は全文カタログに対して実行されるため (ConditionType 値が ByText であるため)、RuleClass で Field メンバーも指定するとエラーになります。
次のコード サンプルは、「Email Down」という一致する用語を含むインシデント レコードを検索する方法を示しています。
ObjectQueryDefinition query = new ObjectQueryDefinition();
query.Select = new SelectClass();
// IncidentからIncidentNumberフィールドの値のみを取得します。
// 検索を呼び出すとき
FieldClass[] incidentFieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "サービス"、
タイプ = "テキスト"
}
};
query.Select.Fields = incidentFieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.Where = new RuleClass[] {
新しいルールクラス()
{
結合 = "AND"、
条件 = "="、
ConditionType = SearchConditionType.ByText,
値 = "メールダウン"
},
};
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);
}
}
}
Search WebMethod で使用されるクラスの正式な説明
前のセクションから、Search WebMethod を適切に実行するには、Web メソッドが呼び出される前に、いくつかのクラスのオブジェクトを作成し、それに応じて設定する必要があることがわかります。
これまでのセクションでは、いくつかの使用例を紹介してきましたが、このセクションでは、さまざまなクラスについて正式に詳細に説明します。
オブジェクトクエリ定義
ObjectQueryDefinition クラスは次のように定義されます。
クラス ObjectQueryDefinition
{
int トップ;
bool 一意;
FromClass From;
SelectClass Select;
List<RuleClass> Where;
List<OrderByClass> OrderBy;
}
クラス定義から、ObjectQueryDefinition は、典型的な SQL SELECT ステートメントのさまざまな部分をモデル化するために使用されていることがわかります。具体的には、次のようになります。
- FROM句
クラス FromClass
- SELECT句
クラス選択クラス
- WHERE句
クラス RuleClass (リストとして実装)
- ORDER BY句
クラス OrderByClass (リストとして実装)
RuleClass (SQL SELECT ステートメントの WHERE 句をモデル化するために使用される) を除き、他のクラスは SQL SELECT ステートメントの対応する句に従って名前が付けられます。
これらのクラスの他に、「Top」という整数メンバー変数があることにも注意してください。これは、検索によって返されるレコードの数を制限するために使用できます(例: 最初の 1000 件の一致する結果を返します。
また、「Distinct」と呼ばれるブール型のメンバー変数もあります。これを使用して、検索結果内の重複する値を排除し、個別の結果を返せます。
次のセクションでは、SELECT ステートメント内のそれぞれの句をモデル化するために使用されるさまざまなコンポーネント クラスについて説明します。
FromClass
FromClass クラスは、一般的な SQL SELECT ステートメントの FROM 句をモデル化するために使用され、次のように定義されます。
クラスFromClass
{
文字列オブジェクト;
List<FromLinkClass> Links;
}
Object メンバー変数には、検索対象となるビジネス オブジェクトの名前を設定する必要があります。
query.From = new FromClass();
query.From.Object = "Incident";
保存された検索を特定の子オブジェクトに対して実行する必要がある場合は、FromLinkClass オブジェクトのリストを使用して、Links メンバー変数も設定する必要があります。
クラス FromLinkClass
{
文字列関係;
文字列オブジェクト;
}
FromLinkClass には 2 つのメンバー変数が含まれています。
- 「Relation」メンバー変数は、親オブジェクトと子オブジェクト間の関係の内部参照名を指定します。
たとえば、「IncidentContainsJournal」関係の場合、関係の内部参照名は空白です。したがって、この関係を使用するには、Objectメンバー変数に子ビジネスオブジェクトの名前を入力し、Relationメンバー変数を空の文字列のままにします。
- 「Object」メンバー変数は、子ビジネスオブジェクトの名前を指定します(例: "ジャーナル
前のコード サンプルから、現在のビジネス オブジェクトに関連する Journal.Email レコードを検索するには、FromClass の Links メンバー変数を次のように設定する必要があることを思い出してください。
query.From.Links = new FromLinkClass[] {
new FromLinkClass {
関係 = "",
オブジェクト = "ジャーナル
}
};
クラスを選択
SelectClass クラスは、一般的な SQL SELECT ステートメントの SELECT 句をモデル化するために使用され、次のように定義されます。
クラス SelectClass
{
bool すべて;
List<FieldClass> Fields;
}
ビジネス オブジェクト内のすべてのフィールドを選択するには、新しい SelectClass オブジェクトを作成し、オブジェクトの「All」メンバー変数を true に設定します。
query.Select = new SelectClass();
query.Select.All = true;
検索がメインビジネスオブジェクト(例: 「インシデント」)とそれに関連する子ビジネスオブジェクト(例: 「Journal.Email」の場合、「All」メンバー変数を true に設定すると、メイン ビジネス オブジェクト内のすべてのフィールドと、子ビジネス オブジェクト内のすべてのフィールドが返されます。
Search Web メソッドによって返されるフィールドのセットを制限するには、FieldClass オブジェクトの新しいリストを作成し、対象のフィールドに対応する FieldClass オブジェクトで初期化します。
前のコード サンプルから、Incident ビジネス オブジェクトの IncidentNumber フィールドと子 Journal.Email オブジェクトの Category フィールドを返すには、次のステートメントが使用されていることを思い出してください。
FieldClass[] fieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "Journal.Category",
タイプ = "テキスト"
}
};
query.Select = new SelectClass();
query.Select.Fields = fieldObjects;
特に、メイン ビジネス オブジェクトのフィールドの場合、フィールドの名前はそのまま指定できますが、子ビジネス オブジェクトのフィールドの場合、フィールド名の前に、関係内の子ビジネス オブジェクトの名前を付ける必要があります。
たとえば、「IncidentContainsJournal」関係が使用されている場合、関係は Incident および Journal (ベース) オブジェクトに対して定義され、カテゴリ フィールドは「Journal.Category」として指定する必要があります。
ルールクラス
RuleClass クラスは、一般的な SQL SELECT ステートメントの WHERE 句をモデル化するために使用され、次のように定義されます。
クラス RuleClass
{
文字列結合;
文字列条件;
検索条件タイプ条件タイプ;
文字列フィールド;
文字列値;
リスト<RuleClass> ルール;
}
Field メンバー変数はフィールドの名前を指定するために使用され、Value メンバー変数はフィールドに対応する値を指定します。
特に、メイン ビジネス オブジェクトのフィールドの場合、フィールドの名前はそのまま指定できますが、子ビジネス オブジェクトのフィールドの場合、フィールド名の前に、関係内の子ビジネス オブジェクトの名前を付ける必要があります。
たとえば、「IncidentContainsJournal」関係が使用されている場合、関係は Incident および Journal (ベース) オブジェクトに対して定義され、カテゴリ フィールドは「Journal.Category」として指定する必要があります。
たとえば、次のステートメントを使用すると、関連する Journal.Email レコードの Category 値が「受信メール」に等しい、優先度値が 1 の Incident レコードを検索できます。
query.Where = 新しいルールクラス[] {
new RuleClass()
{
結合 = "AND"、
Condition = "=",
フィールド = "優先度"、
値 = "1"
},
新しいルールクラス()
{
結合 = "AND"、
Condition = "=",
フィールド = "Journal.Category"、
値 = "受信メール"
}
};
Join プロパティには、「AND」または「OR」のいずれかの値を含めることができ、RuleClass オブジェクトが互いにどのように関連付けられるかを指定します。
Condition メンバー変数は、フィールドと指定された値を関連付けるために使用される比較演算子を指定します。
Condition メンバー変数に許容される値は次のとおりです。
オペレーター
意味
=
等しい
!=
等しくない
>
より大きい
<
未満
>=
より大きいか等しい
<=
以下
ルール条件をグループ化するために、RuleClass クラス内に Rules と呼ばれるメンバー変数があり、オプションで RuleClass オブジェクトのリストを保持できることに注意してください。
したがって、Rules メンバー変数は、RuleClass オブジェクトを構成することによって、関連する RuleClass オブジェクトをグループ化するために使用できます。
前の「ルール条件のグループ化」セクションの次のコード例を思い出してください。
query.Where = new RuleClass[] {
新しいルールクラス
{
結合 = "AND"、
フィールド = "IncidentNumber"、
条件 = "<="、
値 = "10010"
},
新しいルールクラス
{
ルール = 新しいルールクラス[] {
新しいルールクラス
{
フィールド = "Journal.Category"、
条件 = "="、
値 = "送信メール"
},
新しいルールクラス
{
結合 = "OR"、
フィールド = "Journal.Subject",
条件 = "="、
値 = 「緊急リクエスト」
}
}
}
};
上記の例から、トップレベルの 2 番目の RuleClass 内で、Rules メンバー変数が別の内部 RuleClass オブジェクトのリストで初期化され、Journal.Email の条件が表現されていることがわかります。
前の「全文検索」セクションで説明したように、ConditionType が SearchConditionType.ByField の列挙値に設定された通常の SQL スタイルの検索が実行されます。これは検索のデフォルト モードであり、RuleClass のインスタンス化で明示的に指定する必要はありません。
全文検索をサポートするには、RuleClass をインスタンス化するときに、ConditionType を SearchConditionType.ByText の列挙値に設定し、Field メンバーを含めないでください。
クラス順
OrderByClass クラスは、一般的な SQL SELECT ステートメントの Order By 句をモデル化するために使用され、次のように定義されます。
クラス OrderByClass
{
パブリック文字列の名前;
パブリック文字列方向;
}
ここで、Name メンバー変数は並べ替えの対象となるフィールドを指定するために使用され、Direction メンバー変数は、それぞれ「ASC」または「DESC」の値を使用して、レコードを昇順で指定するか降順で指定するかを指定します。
たとえば、前のコード サンプルから、検索によって Incident および関連する Journal.Email レコードが返されるとします。
Incident レコードを IncidentNumber に基づいて昇順で並べ替え、関連する Journal.Subject レコードを Subject に基づいて昇順で並べ替える必要がある場合は、次のコードを使用できます。
query.OrderBy = new OrderByClass[] {
新しい OrderByClass()
{
名前 = "インシデント番号",
方向 = "ASC"
},
新しい OrderByClass()
{
名前 = "Journal.Subject",
方向 = "ASC"
}
};
レコード操作
オブジェクトの作成
この Web メソッドは、単一のビジネス オブジェクトの新しいインスタンスを作成し、他のオブジェクトとの関係を確立することもできます。 オブジェクトが UI を介して対話的に作成された場合は、最初に初期化ルールを実行し、次に指定された値をフィールドに適用し、同じ方法で自動入力、計算、保存、およびビジネス ルールを呼び出します。 検証ルールも実行され、結果のオブジェクト フィールド値が検証に合格しない場合は、保存操作が妨げられる可能性があります。
フィールドは指定された順序で初期化されます。
リクエスト構文:
FRSHEATIntegrationCreateBOResponse CreateObject(string sessionKey, string tenantId, ObjectCommandData commandData)パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- commandData: 作成リクエストに関する情報を含む構造体:
パブリッククラス ObjectCommandData
{
パブリック文字列 ObjectId;
パブリック文字列 ObjectType;
パブリック リスト<ObjectCommandDataFieldValue> フィールド;
パブリック リスト<LinkEntry> LinkToExistent;
}
- ObjectId: 作成するオブジェクトのレコードID
- ObjectType: 作成するオブジェクトのタイプ
- FieldValues: 入力する必要があるビジネス オブジェクトのフィールドのフィールド名と新しい値を含む、名前と値のペアのリスト。
- LinkToExistent: このオブジェクトと他のオブジェクト間の関係を確立するかどうかを制御する LinkEntry クラスを参照します。
パブリッククラス LinkEntry
{
パブリック文字列アクション;
パブリック文字列リレーション;
パブリック文字列 RelatedObjectType;
パブリック文字列 RelationshipName;
パブリック文字列 RelatedObjectId;
パブリック リスト<SearchCondition> SearchCriteria;
}
LinkEntry クラスのフィールド メンバーは次のとおりです。
- アクション: 「リンク」または「リンク解除」 – このオブジェクトを他のオブジェクトとリンクするか、リンク解除するかを決定します。 CreateObject操作では「link」のみが意味を持ちます
- 関係: 確立される関係タイプの関係タグ (管理 UI では内部参照名として表示されます)。
- RelationshipName: 確立する関係タイプの関係名(管理 UI で表示名として表示されます)
- RelatedObjectType: リンクされるオブジェクト参照表記法におけるビジネスオブジェクトのタイプ
- RelatedObjectId: リンクまたはリンク解除するビジネス オブジェクトの recId。 オプション。RelatedObjectId または SearchCriteria のいずれかを指定する必要があります。
- SearchCriteria: このオブジェクトにリンクする必要がある一致するオブジェクトの検索条件を定義する構造体のリスト。
パブリッククラス SearchCondition
{
パブリック文字列 ObjectId;
パブリック文字列 ObjectDisplay;
パブリック文字列 JoinRule;
パブリック文字列条件;
public SearchConditionType ConditionType;
パブリック文字列フィールド名;
パブリック文字列 FieldDisplay;
パブリック文字列 FieldAlias;
パブリック文字列フィールドタイプ;
パブリック文字列 FieldValue;
パブリック文字列 FieldValueDisplay;
パブリック文字列 FieldValueBehavior;
パブリック文字列 FieldStartValue;
パブリック文字列 FieldEndValue;
パブリック リスト<SearchCondition> サブクエリ;
}
- ObjectId: 一致するオブジェクトのrecId
- ObjectDisplay: 定義がありません
- JoinRule: 個々の検索条件をどのように組み合わせるかを決定します。 可能な値は「and」と「or」です
- 条件: フィールド値をどのように一致させるか。 可能な値:
= 等しい
!= 等しくない
> より大きい
< 未満
>= 大きいか等しい
<= 以下
-> 始めに
{} 含む
!{} は含まれません
0は空です
!0 は空ではありません
() リスト内
!() リストにない
>< 範囲内
- ConditionType: テキスト フィールドの検索方法を制御します。 可能な値: 0 – 通常の SQL フィールド検索を使用します (SQL のような、句を含む) 1 – 全文SQLフィールド検索を使用する
- フィールド名: フィールド名
- フィールド値: フィールド値
- FieldValueBehavior: “single” または “list” のいずれか
- FieldStartValue: 「範囲内」条件のみの開始値
- FieldEndValue: 「範囲内」条件のみの終了値
戻り値:
次のように定義される FRSHEATIntegrationCreateBOResponse オブジェクト:
パブリック クラス FRSHEATIntegrationCreateBOResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
パブリック文字列 recId { 取得; 設定; }
public WebServiceBusinessObject obj { get; set; }
}
FRSHEATIntegrationCreateBOResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
- recId – Web メソッドのステータスが「成功」であると仮定して、新しく作成されたレコードの RecId
- obj – ビジネス オブジェクト レコードが正常に作成されたと仮定すると、このフィールドはレコードを WebServiceBusinessObject オブジェクトとして返します。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態
説明
成功
ビジネス オブジェクトを正常に作成できます。
新しく作成されたレコードのRecIdは、レスポンスオブジェクトのrecIdフィールドを介してアクセスでき、objフィールドは新しく作成されたWebServiceBusinessObjectを参照します。
エラー
ビジネス オブジェクトを正常に作成できません。recId フィールドと obj フィールドは null になり、例外は exceptionReason フィールドに格納されます。
典型的なエラーの 1 つは、指定されたビジネス オブジェクトがテナント内に存在しない場合に発生する、テーブルが見つからない例外です。 ビジネスオブジェクトの名前が正しく入力されているか再度確認してください(例: 「インシデント」、「プロファイル.従業員」など)
他によく発生するエラーは、ビジネス オブジェクトに指定されたフィールドが存在しない場合に発生します。この場合、エラー メッセージの形式は次のようになります。
ObjectTableMap: フィールド <FieldName> がテーブル <Business Object>に見つかりません
フィールド名が正しく入力されていること、および特定のビジネス オブジェクトに対して実際に定義されていることを再確認してください。
3 番目によくあるエラーは、関連する検証リストに存在しない値をフィールドに指定することです。このような場合、次の例外が発生します。
<BusinessObject>.<Field>:`<FieldValue>` は検証リストにありません
日付/時刻の値を指定するには、文字列値を ISO 8601 形式を使用して指定し、値自体は UTC を基準にする必要があります。
したがって、日付/時刻の値は次の 2 つの方法のいずれかで指定できます。
yyyy-mm-dd 時:mm
または
yyyy-mm-dd木:mm
日付と時刻の値を区切るには、スペース文字または「T」文字を使用できます。
以下は、上記の 2 つの形式を基準にして、2013 年 3 月 26 日 18:38 UTC の日付/時刻値を指定する 2 つの例です。
2013-03-26 18:38
2013-03-26T18:38
例:
次の例では、最初に特定のフィールド値を持つ新しい変更レコードを作成し、次に Search() Web メソッドを使用して既存の CI.Computer レコードを検索し、CreateObject() Web メソッドを使用して 2 つのレコードをリンクします。
ObjectCommandData data = new ObjectCommandData();
data.ObjectType = "Change#";
List<ObjectCommandDataFieldValue> dataFields = new List<ObjectCommandDataFieldValue>();
辞書<string, object> fields = 新しい辞書<string, object>();
フィールド["リクエストリンク"] = "FB884D18F7B746A0992880F2DFFE749C";
fields["Subject"] = "ハードディスクを交換する必要があります";
fields["Description"] = "ハードドライブがクラッシュしました。ベンダーから新しいドライブに交換する必要があります";
fields["ステータス"] = "ログに記録されました";
fields["TypeOfChange"] = "Major";
fields["OwnerTeam"] = "運用";
fields["所有者"] = "管理者";
fields["影響"] = "中";
fields["緊急度"] = "中";
fields["CABVoteExpirationDateTime"] = "2013-03-26 18:38:30";
foreach (fields.Keys 内の文字列キー)
{
dataFields.Add(新しいObjectCommandDataFieldValue()
{
名前 = キー、
値 = fields[キー].ToString()
});
}
data.Fields = dataFields.ToArray();
// ここでCI.Computerレコードを識別し、
// 新しい変更レコード
// この例では、CI.Computerレコードを検索します
// 「APAC-DEPOT-SERV01」という名前で、そのRecIdを取得します
ObjectQueryDefinition ciQuery = new ObjectQueryDefinition();
// CI.Computer レコードの RecId フィールドのみを取得します
FieldClass[] ciFieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "RecId"、
タイプ = "テキスト"
}
};
ciQuery.Select = new SelectClass();
ciQuery.Select.Fields = ciFieldObjects;
ciQuery.From = new FromClass();
// CI.Computer メンバー オブジェクトに対してレコードを検索します
ciQuery.From.Object = "CI.Computer";
ciQuery.Where = new RuleClass[]
{
// CI.Computerを検索するための条件を指定します
// ここでは、CI.Computerを名前で検索します
new RuleClass()
{
条件 = "="、
フィールド = "名前"、
値 = "APAC-DEPOT-SERV01"
}
};
// クエリのObjectQueryDefinitionを渡します
FRSHEATIntegrationSearchResponse searchResponse = frSvc.Search(authSessionKey, tenantId, ciQuery);
WebServiceBusinessObject[][] cilist = searchResponse.objList;
// CIレコードが名前によって一意に識別され、
// 上記のクエリは他のテーブルと結合しないので、
// cilist[0][0]にアクセスすることでCIレコードを見つけることができます。
// WebServiceBusinessObjects のリストのリスト
WebServiceBusinessObject ci = cilist[0][0];
文字列 ciRecId = ci.RecID;
// 新しい変更レコードを CI にリンクするための LinkEntry レコードを定義します
// 変更のRecId(つまり ciRecId), as
// 上記で決定
data.LinkToExistent = new LinkEntry[]
{
新しいLinkEntry()
{
アクション = "リンク"、
関係 = "",
関連オブジェクトタイプ = "CI
関連オブジェクトID = ciRecId
}
};
// レコードの作成が成功した場合、結果変数には
// 新しい変更レコードの RecId。それ以外の場合は null になります
FRSHEATIntegrationCreateBOResponse result = frSvc.CreateObject(authSessionKey, tenantId, data);
if (result.status == "Success")
{
Console.WriteLine("A new Change record is created with RecId of ", result.recId);
}
次の例では、新しい Profile.Employee レコードを作成し、ユーザーをそれぞれの役割とチームにリンクします。
特に、パスワード値はプレーンテキストで指定されていることに注意してください。レコードを保存すると、パスワード値は自動的に内部ハッシュ値に変換されます。
ObjectCommandData data = new ObjectCommandData();
data.ObjectType = "Profile#Employee";
List<ObjectCommandDataFieldValue> dataFields = new List<ObjectCommandDataFieldValue>();
辞書<string, object> fields = 新しい辞書<string, object>();
fields["ステータス"] = "アクティブ";
fields["FirstName"] = "ブライアン";
fields["LastName"] = "ウィルソン";
fields["ログインID"] = "BWilson";
フィールド["IsInternalAuth"] = true;
// 従業員のパスワードを設定する際、プレーンテキスト
// ここでパスワードが指定されます - ハッシュ値に変換されます
// レコードの保存時
fields["InternalAuthPasswd"] = "Manage1t";
fields["PrimaryEmail"] = "[email protected]";
fields["電話1"] = "14158665309";
// 新入社員のマネージャーとして機能する「管理者」ユーザーの RecId
フィールド["ManagerLink"] = "FB884D18F7B746A0992880F2DFFE749C";
// 新入社員の組織単位の「GMI」組織単位の RecId
フィールド["OrgUnitLink"] = "4A05123D660F408997A4FEE714DAD111";
fields["チーム"] = "IT";
fields["Department"] = "Operations";
fields["タイトル"] = "管理者";
foreach (fields.Keys 内の文字列キー)
{
dataFields.Add(新しいObjectCommandDataFieldValue()
{
名前 = キー、
値 = fields[キー].ToString()
});
}
data.Fields = dataFields.ToArray();
data.LinkToExistent = new LinkEntry[]
{
// まず、新入社員を「SelfService」にリンクし、
// RecID による「ServiceDeskAnalyst」ロール
// 関係の内部参照名
// Profile.EmployeeとFrsdefroleは空なので、そのままにしておきます
// この場合、LinkEntry の Relation 属性は空です
// 「SelfService」ロールへのリンク
新しいLinkEntry()
{
アクション = "リンク"、
関係 = "",
RelatedObjectType = "Frs_def_role#",
RelatedObjectId = "0a4724d8478b451abea3fb44d33db1b6"
},
// 「ServiceDeskAnalyst」ロールへのリンク
新しいLinkEntry()
{
アクション = "リンク"、
関係 = "",
RelatedObjectType = "Frs_def_role#",
RelatedObjectId = "06d780f5d7d34119be0d1bc8fc997947"
},
// 次に、新入社員を「IT」チームと「HR」チームにリンクします。
// 関係の内部参照名
// Profile.EmployeeとStandardUserTeamは「Rev2」なので、
// LinkEntryのRelation属性でこれを指定します
// 「IT」チームへのリンク
新しいLinkEntry()
{
アクション = "リンク"、
関係 = "Rev2"、
RelatedObjectType = "StandardUserTeam#",
RelatedObjectId = "10F60157A4F34A4F9DDB140E2328C7A6"
},
// 「HR」チームへのリンク
新しいLinkEntry()
{
アクション = "リンク"、
関係 = "Rev2"、
RelatedObjectType = "StandardUserTeam#",
RelatedObjectId = "1FF47B9EDA3049CC92458CE3249BA349"
}
};
FRSHEATIntegrationCreateBOResponse result = frSvc.CreateObject(authSessionKey, tenantId, data);
if (result.status == "Success")
{
Console.WriteLine("新入社員レコードが recId で作成されました ", result.recId);
}
オブジェクトの更新
この Web メソッドは、フィールド値を変更することで単一のオブジェクトを更新し、他のオブジェクトとの関係を確立したり解除したりすることもできます。 更新中に自動入力、計算、保存、ビジネス ルールが実行され、追加のフィールド変更がトリガーされる可能性があることに注意してください。 検証ルールも実行され、結果のオブジェクト フィールド値が検証に合格しない場合は更新操作がブロックされる可能性があります。
更新中も操作の順序は保持されます。
リクエスト構文:
FRSHEATIntegrationUpdateBOResponse UpdateObject(string sessionKey, string tenantId, ObjectCommandData commandData)パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- commandData: CreateObject リクエストの ObjectCommandData の説明を参照してください
戻り値:
次のように定義される FRSHEATIntegrationUpdateBOResponse オブジェクト:
パブリッククラス FRSHEATIntegrationUpdateBOResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
パブリック文字列 recId { 取得; 設定; }
public WebServiceBusinessObject obj { get; set; }
}
FRSHEATIntegrationUpdateBOResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
- recId – Web メソッドのステータスが「成功」であると仮定した場合の更新されたレコードの RecId
- obj – ビジネス オブジェクト レコードが正常に更新されると仮定すると、このフィールドは更新されたレコードを WebServiceBusinessObject オブジェクトとして返します。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態
説明
成功
ビジネス オブジェクトを正常に更新できます。
更新されたレコードのRecIdは、レスポンスオブジェクトのrecIdフィールドを介してアクセスでき、objフィールドは更新されたWebServiceBusinessObjectを参照します。
エラー
ビジネス オブジェクトを正常に更新できません。recId フィールドと obj フィールドは null になり、例外は exceptionReason フィールドに格納されます。
典型的なエラーの 1 つは、指定されたビジネス オブジェクトがテナント内に存在しない場合に発生する、テーブルが見つからない例外です。 ビジネスオブジェクトの名前が正しく入力されているか再度確認してください(例: 「インシデント」、「プロファイル.従業員」など)
他によく発生するエラーは、ビジネス オブジェクトに指定されたフィールドが存在しない場合に発生します。この場合、エラー メッセージの形式は次のようになります。
ObjectTableMap: フィールド <FieldName> がテーブル <Business Object>に見つかりません
フィールド名が正しく入力されていること、および特定のビジネス オブジェクトに対して実際に定義されていることを再確認してください。
3 番目によくあるエラーは、関連する検証リストに存在しない値をフィールドに指定することです。このような場合、次の例外が発生します。
<BusinessObject>.<Field>:`<FieldValue>` は検証リストにありません
日付/時刻の値を指定するには、文字列値を ISO 8601 形式を使用して指定し、値自体は UTC を基準にする必要があります。
したがって、日付/時刻の値は次の 2 つの方法のいずれかで指定できます。
yyyy-mm-dd 時:mm
または
yyyy-mm-dd木:mm
日付と時刻の値を区切るには、スペース文字または「T」文字を使用できます。
以下は、上記の 2 つの形式を基準にして、2013 年 3 月 26 日 18:38 UTC の日付/時刻値を指定する 2 つの例です。
2013-03-26 18:38
2013-03-26T18:38
例:
次の例では、Search() Web メソッドを使用して既存の Change レコードと CI.Computer レコードを検索し、UpdateObject() Web メソッドを使用して 2 つのレコードをリンクします。
// まず、ChangeNumberを使用して更新する変更レコードを検索します
// (例: 変更 21)
ObjectQueryDefinition changeQuery = new ObjectQueryDefinition();
// 変更レコードの RecId フィールドのみを取得します
FieldClass[] changeFieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "RecId"、
タイプ = "テキスト"
}
};
changeQuery.Select = 新しい SelectClass();
changeQuery.Select.Fields = changeFieldObjects;
変更クエリ.From = 新しい FromClass();
// Change オブジェクトに対してレコードを検索します
changeQuery.From.Object = "変更";
changeQuery.Where = 新しいルールクラス[] {
new RuleClass()
{
// 変更を検索するための条件を指定します
// ここでは、ChangeNumberで変更を検索します
条件 = "="、
フィールド = "ChangeNumber"、
値 = "21"
}
};
// クエリのObjectQueryDefinitionを渡します
FRSHEATIntegrationSearchResponse changeSearchResponse = frSvc.Search(authSessionKey, tenantId, changeQuery);
WebServiceBusinessObject[][] changeList = changeSearchResponse.objList;
// 変更レコードが一意に識別されると仮定すると、
// ChangeNumber、そして上記のクエリは他のクエリと結合しないため
// テーブルにアクセスすることで、変更レコードを見つけることができるはずです。
// changeList[0][0]、WebServiceBusinessObjectsのリストのリスト内
WebServiceBusinessObjectの変更 = changeList[0][0];
文字列 changeRecId = change.RecID;
// CI.Computerレコードを見つけて、既存のChangeとリンクします。
// ここではCI.Computerレコードを検索します。
// "APAC-DEPOT-SERV01" の名前とその RecId を取得します
ObjectQueryDefinition ciQuery = new ObjectQueryDefinition();
// 一致する結果の CI の RecId フィールドのみを取得します
FieldClass[] ciFieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "RecId"、
タイプ = "テキスト"
}
};
ciQuery.Select = new SelectClass();
ciQuery.Select.Fields = ciFieldObjects;
ciQuery.From = new FromClass();
// CI.Computer メンバー オブジェクトに対してレコードを検索します
ciQuery.From.Object = "CI.Computer";
ciQuery.Where = new RuleClass[]
{
// CI.Computer を名前で検索する
new RuleClass()
{
条件 = "="、
フィールド = "名前"、
値 = "EMEA-EXCH-SERV01"
}
};
// クエリのObjectQueryDefinitionを渡します
FRSHEATIntegrationSearchResponse ciSearchResponse = frSvc.Search(authSessionKey, tenantId, ciQuery);
WebServiceBusinessObject[][] cilist = ciSearchResponse.objList;
// CIレコードが名前によって一意に識別され、
// 上記のクエリは他のテーブルと結合しないので、
// cilist[0][0]にアクセスすることでCIレコードを見つけることができる。
// WebServiceBusinessObjects のリストのリスト
WebServiceBusinessObject ci = cilist[0][0];
// CIのRecIdフィールドのみを取得するため、
// フィールドのリストの最初の項目として、つまり ci.FieldValues[0]
文字列 ciRecId = (文字列)ci.FieldValues[0].Value;
// この時点で、変更レコードとCIレコードのRecIdが取得できました。
// 更新を続行できます
// ObjectCommandDataの場合は、
// 上で決定された、更新するレコードを検索するためのもの
ObjectCommandData data = new ObjectCommandData();
data.ObjectType = "Change#";
data.ObjectId = changeRecId;
List<ObjectCommandDataFieldValue> dataFields = new List<ObjectCommandDataFieldValue>();
辞書<string, object> fields = 新しい辞書<string, object>();
// 既存のフィールド値を更新できることを示すために、
// 既存の変更レコードの緊急度を「高」にする
fields["緊急度"] = "中";
// CABVoteExpirationDateTime を特定の日付/時刻値に更新します
fields["CABVoteExpirationDateTime"] = "2013-03-26 18:38:30";
foreach (fields.Keys 内の文字列キー)
{
dataFields.Add(新しいObjectCommandDataFieldValue()
{
名前 = キー、
値 = fields[キー].ToString()
});
}
data.Fields = dataFields.ToArray();
data.LinkToExistent = new LinkEntry[]
{
新しいLinkEntry()
{
アクション = "リンク"、
関係 = "",
関連オブジェクトタイプ = "CI
関連オブジェクトID = ciRecId
}
};
FRSHEATIntegrationUpdateBOResponse response = frSvc.UpdateObject(authSessionKey, tenantId, data);
if (response.exceptionReason != null)
{
Console.WriteLine("レコードの更新中に次のエラーが発生しました: ", response.exceptionReason);
}
オブジェクトを削除
指定されたビジネス オブジェクト レコードを削除します。
リクエスト構文:
FRSHEATIntegrationDeleteBOResponse DeleteObject(string sessionKey, string tenantId, ObjectCommandData commandData)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- commandData: CreateObject リクエストの ObjectCommandData の説明を参照してください
戻り値:
次のように定義される FRSHEATIntegrationDeleteBOResponse オブジェクト:
public class FRSHEATIntegrationDeleteBOResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
}
FRSHEATIntegrationDeleteBOResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態
説明
成功
ビジネス オブジェクト レコードを正常に削除できます。
レコードがテナントから正常に削除された場合、または指定されたレコードがテナント内に見つからない場合は、Success の値が返されることに注意してください。
エラー
指定されたレコードをシステムから削除するプロセス中にエラーが発生しました。
通常、指定されたビジネス オブジェクトがシステムに存在しない場合にエラーが発生する可能性があります。この場合、エラー メッセージは次のようになります。
ビジネスオブジェクトの定義 <BusinessObject>
このような場合は、指定されたビジネス オブジェクトがテナント内に存在することを確認してください。
例:
次の例では、指定された RecID 値を持つインシデント レコードを削除します。
ObjectCommandData data = new ObjectCommandData();
data.ObjectType = "Incident#";
data.ObjectId = "96F889A8CE6E4F9C8B3A99852F788670";
FRSHEATIntegrationDeleteBOResponse response = frSvc.DeleteObject(authSessionKey, tenantId, data);
if (response.status != "Success")
{
Console.WriteLine("レコードの削除中に次のエラーが発生しました: " response.exceptionReason);
}
添付ファイル
添付ファイルを追加
この Web メソッドは、指定されたビジネス オブジェクト レコードに添付ファイルを追加します。
リクエスト構文:
FRSHEATIntegrationAddAttachmentResponse AddAttachment(string sessionKey, string tenantId, ObjectAttachmentCommandData commandData)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- commandData: 添付ファイルに関する情報を含む構造体:
パブリッククラス ObjectAttachmentCommandData
{
パブリック文字列 ObjectId;
パブリック文字列 ObjectType;
パブリック文字列ファイル名;
パブリックByte[]ファイルデータ;
}
- ObjectId: 新しい添付ファイルのレコード ID。
- ObjectType: オブジェクト参照表記法でこの添付ファイルが添付されるメインのビジネス オブジェクトのタイプ。
- fileName: ファイルの名前。
- fileData: 実際のファイルバイト数。
戻り値:
次のように定義される FRSHEATIntegrationAddAttachmentResponse オブジェクト:
public class FRSHEATIntegrationAddAttachmentResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
}
FRSHEATIntegrationAddAttachmentResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態
説明
成功
添付ファイルをビジネス オブジェクト レコードに正常に追加できます。
エラー
添付ファイルをビジネス オブジェクト レコードに正常に追加できず、例外情報が応答オブジェクトの exceptionReason フィールドに保存されます。
エラーの一般的な原因の 1 つは、添付ファイルのファイル拡張子が特定のテナントで許可されていない場合です。この場合、エラー メッセージの形式は次のようになります。
アップロードされたファイルは制限されたファイル拡張子です。 アップロードに許可されているファイル拡張子のリストについては、システム管理者にお問い合わせください。
エラーのもう 1 つの一般的な原因は、ビジネス オブジェクト レコードが正常に見つからない場合です。この場合、エラー メッセージの形式は次のようになります。
添付ファイルのアップロードに失敗しました。
エラーの 3 番目の原因は、指定されたビジネス オブジェクトがテナントに存在しない場合に発生します。この場合、エラー メッセージの形式は次のようになります。
ビジネスオブジェクトの定義 <Business Object>
例:
次の例では、ユーザーのローカル ファイル システムからサンプル イメージを読み取り、指定されたインシデント レコードにファイルを添付します。
定数文字列ファイル名 = "C:\\\\Temp\\\\sample.jpg";
(FileStream fs = new FileStream(fileName, FileMode.Open, FileAccess.Read) を使用します)
{
(BinaryReader r = new BinaryReader(fs)) を使用します
{
byte[] AttachmentData = 新しいbyte[fs.Length];
(int i = 0; i < fs.Length; i ) の場合
{
AttachmentData[i] = r.ReadByte();
}
ObjectAttachmentCommandData data = new ObjectAttachmentCommandData()
{
ObjectId = "9981FBEBAA8B4EE2820364505855ABC2",
オブジェクトタイプ = "インシデント
ファイル名 = "sample.png",
ファイルデータ = 添付ファイルデータ
};
FRSHEATIntegrationAddAttachmentResponse response = frSvc.AddAttachment(authSessionKey, tenantId, data);
if (response.status != "Success")
{
Console.WriteLine("レコードに添付ファイルを追加中に次のエラーが発生しました: " response.exceptionReason);
}
}
}
添付ファイルを読む
この Web メソッドは、RecId 値によって識別される特定の添付ファイル レコードのデータを読み取るために使用されます。
リクエスト構文:
FRSHEATIntegrationReadAttachmentResponse ReadAttachment(string sessionKey, string tenantId, ObjectAttachmentCommandData commandData)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- commandData: 添付ファイルに関する情報を含む構造体: パブリッククラス ObjectAttachmentCommandData { パブリック文字列 ObjectId; }
- ObjectId: 新しい添付ファイルのレコード ID。
戻り値:
次のように定義される FRSHEATIntegrationReadAttachmentResponse オブジェクト:
public class FRSHEATIntegrationReadAttachmentResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック文字列例外理由 { 取得; 設定; }
パブリック byte[] attachmentData { 取得; 設定; }
}
FRSHEATIntegrationReadAttachmentResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、操作が成功したかどうかを示すステータス値が表示されます。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- exceptionReason – WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
- attachmentData - 指定された添付ファイルの内容を含むバイト配列
次の表に、使用可能なステータス値と、それらの解釈方法を示します。
状態
説明
成功
指定された添付ファイル レコードはテナントから正常に取得され、応答オブジェクトの attachmentData バイト配列フィールドを介してデータが返されます。
見つかりません
指定された添付ファイル レコードがテナント内に見つかりません。
添付ファイル ビジネス オブジェクト内のレコードを再確認し、目的の添付ファイル レコードが実際に存在することを確認します。
エラー
テナントから添付ファイル レコードを取得中に予期しないエラーが発生し、例外情報が応答オブジェクトの exceptionReason フィールドに格納されます。
ほとんどの場合、添付ファイルの取得の結果は「成功」または「見つかりません」のいずれかのステータスになります。
例:
byte[] 添付ファイルデータ;
定数文字列ファイル名 = "C:\\\\Temp\\\\test.png";
ObjectAttachmentCommandData data = new ObjectAttachmentCommandData()
{
ObjectId = "94069732037142E7BF3D81DB02128289", // 添付ファイルレコードの RecId
};
FRSHEATIntegrationReadAttachmentResponse response = frSvc.ReadAttachment(authSessionKey, tenantId, data);
if (response.status == "Success")
{
添付ファイルデータ = response.attachmentData;
if (AttachmentData != null)
{
(FileStream fs = new FileStream(fileName, FileMode.Create) を使用します)
{
using (BinaryWriter w = new BinaryWriter(fs))
{
(int i = 0; i < AttachmentData.Length; i ) の場合
{
w.Write(AttachmentData[i]);
}
}
}
}
}
そうでない場合 (response.status == "NotFound")
{
Console.WriteLine("指定された RecId の添付ファイル レコードがテナント内に見つかりません");
}
それ以外
{
Console.WriteLine("レコードから添付ファイルを読み取っているときに次のエラーが発生しました: " response.exceptionReason);
}
重要な注意: .NET ベースの Web サービス クライアントの場合、Web サービス経由で大きな添付ファイルを取得するときに、アプリケーションで次のエラーが発生する可能性があります。
CommunicationException が発生しました: 受信メッセージの最大メッセージ サイズ クォータ (65536) を超えました。 クォータを増やすには、適切なバインディング要素の MaxReceivedMessageSize プロパティを使用します。
ここで、Webサービスを利用する.NETクライアントアプリケーションは、大きな添付ファイルのサイズに対応できるように、App.configファイルで「MaxReceivedMessageSize」および「MaxBufferSize」属性が十分に大きい値に設定されるように構成する必要があります。例:
<binding name=\"IPCMServiceSoap\" closeTimeout=\"00:01:00\" openTimeout=\"00:01:00\"
受信タイムアウト="00🕙00" 送信タイムアウト="00:01:00" クッキーを許可する="false"
bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard"
最大バッファサイズ = "65536" 最大バッファプールサイズ = "524288" 最大受信メッセージサイズ = "65536"
messageEncoding="テキスト" textEncoding="utf-8" transferMode="バッファリング"
useDefaultWebProxy="true">
...
</binding>
上記のサイズ値はバイト単位で表されることに注意してください。
メタデータ アクセス
ビジネス オブジェクト アップローダー ツールを使用して、既存のビジネス オブジェクト セットを FRS HEAT テナントにインポートできます。 このツールは、パブリック Web サービスを使用して FRS SaaS アプリケーション サーバーと通信し、ユーザーのログイン、データ入力フォームの入力、ビジネス オブジェクト データのアップロードを容易にします。
ビジネス オブジェクト アップローダーのワークフローは次のとおりです。
- インスタンスにログインします。 許可されるすべてのビジネス オブジェクトのリストを読み込みます。 ビジネスオブジェクトを選択し、 選択したオブジェクトのメタデータを読み込みます。 必要に応じて、インポートするフィールドのデータを入力します。 新しいオブジェクトをシステムに送信する
API を設計する際に、作成できるオブジェクトを知るには、許可されたオブジェクトのリストを取得する必要があります (GetAllAllowedObjectNames)
オブジェクト作成呼び出しに送信するフィールドを知るには、メタデータ (GetSchemaForObject) を取得する必要があります。
場合によっては、「特別な」フィールド (RecID など) が表示されている状態でもオブジェクトをアップロードする必要があることがあります (GetAllSchemaForObject)。
オブジェクトを取得するスキーマ
ビジネス オブジェクトの背後にあるメタデータの XML バージョンを取得します。 このプロセスでは、RecIDなど、エンドユーザーの消費に適さないプロパティを除外します。
リクエスト構文:
文字列 GetSchemaForObject(文字列 sessionKey、文字列 tenantId、文字列 objectName)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- objectName: ビジネスオブジェクトの名前(オブジェクト参照表記法)(例: "Incident#")
戻り値:
XML で表現される、指定されたビジネス オブジェクトのスキーマを表す文字列値。
例:
文字列 schemaDoc = frSvc.GetSchemaForObject(authSessionKey, tenantId, "インシデント
GetAllSchemaForObject
RecID などのすべてのフィールドを含む、オブジェクトの背後にあるメタデータの XML バージョンを取得します。
リクエスト構文:
文字列 GetAllSchemaForObject(文字列 sessionKey、文字列 tenantId、文字列 objectName)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
- objectName: ビジネスオブジェクトの名前(オブジェクト参照表記法)(例: "Incident#")
戻り値:
XML で表現される、指定されたビジネス オブジェクトのスキーマを表す文字列値。
例:
文字列 schemaDoc = frSvc.GetSchemaForObject(authSessionKey, tenantId, "インシデント
GetAllAllowedObjectNames
すべてのビジネス オブジェクトのリストを取得します。
リクエスト構文:
List<string> GetAllAllowedObjectNames(string sessionKey, string tenantId);
パラメータ:
- sessionKey: 以前の接続要求で受信したキー
- tenantId: キーが認証されるテナント。
戻り値:
各項目がビジネス オブジェクトの名前に対応する文字列の配列。
例:
文字列[] boNameArray = frSvc.GetAllAllowedObjectNames(authSessionKey、テナントID);
