FRSHEAT統合WebサービスURL
FRSHEATIntegration Web サービスには、次の例のようなリンクからアクセスできます。
https://<TenantName>/ServiceAPI/FRSHEATIntegration.asmx
を<TenantName>、特定のテナントに対応するホスト名に置き換えます。
上記の URL にアクセスすると、利用可能な Web メソッドに関する情報が提供されることに注意してください。

対応する WSDL ファイルにアクセスするには、以下のリンク例に示すように、前の URL の末尾に「?wsdl」を追加します。https://<TenantName>/ServiceAPI/FRSHEATIntegration.asmx?wsdl

接続の確立と役割の選択
アプリケーションが SaaS プラットフォーム上の Web サービス API にアクセスするには、テナントに関して適切に認証および承認されている必要があります。 これは、後続の Web サービス操作を実行する前に、まず Connect() Web メソッドを呼び出すことによって実現されます。
接続する
Connect WebMethod は、Web サービス ユーザーが適切に認証され、指定されたロールに属していることを確認するために、認証と承認の両方の操作を実行します。
リクエスト構文:
FRSHEATIntegrationConnectionResponse Connect(string userName, string password, string tenantId, string role)
パラメータ:
userName: セッションが作成される loginId。 loginId は、Profile.Employee ビジネス オブジェクト (Profile テーブル) の LoginID 列に対して検索されます。
パスワード: ユーザーのパスワード。 従業員レコードの構成に応じて、内部パスワードまたは外部 (アクティブ ディレクトリ) パスワードのいずれかを使用できます。
tenantId: セッションが作成されるテナント。 テナント ID は、ConfigDB データベースの Tenants ビジネス オブジェクトの「TenantURL」フィールドと照合されます。 認証が成功するには、テナント レコードが「アクティブ」状態である必要があります。
ロール: 指定されたユーザーがログインするロール。
戻り値:
次のように定義される FRSHEATIntegrationConnectionResponse オブジェクト:
public class FRSHEATIntegrationConnectionResponse
{
パブリック文字列 connectionStatus;
パブリック文字列セッションキー;
パブリック文字列 exceptionReason;
}
FRSHEATIntegrationConnectionResponse クラスは次のフィールドで構成されます。
- connectionStatus – このフィールドは、接続の状態を示すステータス値を提供します。 使用可能なステータス値の詳細な説明は、以下の表に記載されています。
- sessionKey – 後続のすべての Web サービス操作で使用する必要がある sessionKey。 このフィールドは、connectionStatus の値が「Success」の場合にのみ入力され、それ以外の場合は値は null になります。
- exceptionReason – Connect WebMethod の実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
Connect WebMethod 操作が正常に完了すると、sessionKey は FRSHEATIntegrationConnectionResponse オブジェクトの対応するメンバーに格納されます。
ただし、接続操作中 (認証フェーズまたは承認フェーズのいずれか) にエラーが発生した場合は、サーバーによって SOAP 例外がスローされ、Web サービス クライアントはそれに応じて例外を処理する必要があります。
次の表は、Connect WebMethod の実行中に発生する可能性のある例外の種類を示しています。
SOAP例外 | 説明 |
|---|---|
アクセスが拒否されました | 指定されたユーザ名がテナント内に存在しないか、または指定されたパスワードがユーザ名に対して無効です。 Connect Web メソッドに渡された資格情報を再確認し、正しく指定されていることを確認します。 |
テナントが見つかりません | 指定された TenantURL が見つからないか、テナントが現在「アクティブ」ステータスではありません。 TenantURL を再確認し、テナントにアクセスするための正しい URL であることを確認します。 TenantURL が正しい場合は、指定されたテナントのステータスについて FRS オペレーションに再度確認してください。 |
メンテナンス中のテナント | 指定されたテナントは現在メンテナンス モードです。 テナントがメンテナンス モードになっているかどうかを確認し、テナントがいつアクティブ状態に戻るかを FRS オペレーションに再確認します。 |
無効な役割 | 指定されたロール定義がテナントで使用できないか、ユーザーが現在指定されたロールに関連付けられていません。 ロールがテナント内に実際に存在するかどうか、およびユーザーが指定されたロールに属しているかどうかを確認します。 |
セッション期限切れ | SessionKey は期限切れになったセッションを参照します。 これは通常、API 操作が以前の Connect Web メソッド呼び出しからの SessionKey を使用し、非アクティブのためにセッションが期限切れになった場合に発生します。 このような状況が発生するたびに、Connect Web メソッド呼び出しを再度実行して、新しいセッションキーを取得し、さらにアクションを実行する必要があります。 これについては次のセクションで説明します。 |
重要な注意: このドキュメントで説明する以降のすべての Web メソッドでは、同じ sessionKey 値を再利用すると、ユーザーが認証/承認エラーに遭遇する可能性があります。Web サービス クライアントは、このドキュメントで説明する残りの Web メソッドを実行する際に、接続エラーの可能性を考慮する必要があります。
例
FRSHEATIntegration frSvc = new FRSHEATIntegration();
FRSHEATIntegrationConnectionResponse connectresponse = frSvc.Connect(username, password, tenantId, role);
if (connectresponse.connectionStatus == "Success")
{
...
}
セッションの有効期限の処理
セッション キーを取得するために Connect WebMethod への最初の呼び出しを行った後、通常、Web サービス クライアントは、Search、UpdateObject などの後続のすべての WebMethod 操作を呼び出すために同じセッション キー値を再利用します。
Web サービス クライアントが一定時間アイドル状態のままで、テナントに設定されているセッション タイムアウト値を超えると、セッションが期限切れになり、以前に取得されたセッション キーは無効になります。
セッションの有効期限が切れた後、クライアントが後続の操作 (検索など) に有効期限が切れたセッションキーを使用しようとすると、サーバーから SOAP 例外が返され、セッションが実際に期限切れになったことがクライアントに通知されます。
明示的な SOAP 例外をクライアントに返すことで、クライアントは標準の例外処理手法を使用して Connect WebMethod を再度呼び出し、まったく新しいセッションキーを取得できます。このセッションキーは、後続の操作で使用できます。
.NET ベースの Web サービス クライアントの場合、FRSHEATIntegration API への参照は、Web 参照またはサービス参照のいずれかを使用して確立できます。SOAP 例外を処理するコードは、参照の種類によって若干異なります。
次のコード サンプルは、Web サービス クライアントが FRSHEATIntegration API への Web 参照を使用して定義されている場合に、これを実現する方法を示しています。
ObjectQueryDefinition query = new ObjectQueryDefinition();
query.Select = new SelectClass();
FieldClass[] incidentFieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "サービス"、
タイプ = "テキスト"
}
};
query.Select.Fields = incidentFieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.Where = new RuleClass[] {
新しいルールクラス()
{
結合 = "AND"、
条件 = "="、
フィールド = "IncidentNumber"、
値 = "10001"
}
};
FRSHEATIntegrationSearchResponse searchResponse = null;
試す
{
searchResponse = frSvc.Search(authSessionKey, tenantId, query);
}
catch (SoapException soapException)
{
if (soapException.Actor == "SessionExpired")
{
connectresponse = frSvc.Connect(username, password, tenantId, role);
if (connectresponse.connectionStatus == "Success")
{
authSessionKey = connectresponse.sessionKey;
searchResponse = frSvc.Search(connectresponse.sessionKey、テナントID、クエリ);
}
}
}
if (searchResponse != null && searchResponse.status == "Success")
{
WebServiceBusinessObject[][] incidentList = searchResponse.objList;
foreach (WebServiceBusinessObject[]incidentOuterList inincidentList)
{
foreach (WebServiceBusinessObject incident in incidentOuterList)
{
Console.WriteLine("インシデント は選択基準に一致します",incident.FieldValues[0].Value);
}
}
}
特に、次のコード フラグメントに注意してください。
試す
{
searchResponse = frSvc.Search(authSessionKey, tenantId, query);
}
catch (SoapException soapException)
{
if (soapException.Actor == "SessionExpired")
{
connectresponse = frSvc.Connect(username, password, tenantId, role);
if (connectresponse.connectionStatus == "Success")
{
authSessionKey = connectresponse.sessionKey;
searchResponse = frSvc.Search(authSessionKey、テナントID、クエリ);
}
}
}
Search WebMethod 操作が try-catch ブロック内にラップされていることに注意してください。
セッションの有効期限切れに対応する SOAP 例外が発生した場合は、SoapException の Actor プロパティを検査して、接続エラーがセッション タイムアウトによるものかどうかを判断できます。
例外の原因がセッション タイムアウトである場合は、Connect WebMethod を再度呼び出して、新しいセッション キーを取得します。
authSessionKey がグローバルにアクセス可能な文字列であると仮定すると、これは connectresponse オブジェクトの sessionkey プロパティに更新され、Search WebMethod を 2 回目に正常に実行できるようになります。
次のコード サンプルは、Web サービス クライアントが FRSHEATIntegration API へのサービス参照を使用して定義されている場合に、これを実現する方法を示しています。
ObjectQueryDefinition query = new ObjectQueryDefinition();
query.Select = new SelectClass();
FieldClass[] incidentFieldObjects = new FieldClass[] {
新しいフィールドクラス()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
新しいフィールドクラス()
{
名前 = "サービス"、
タイプ = "テキスト"
}
};
query.Select.Fields = incidentFieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.Where = new RuleClass[] {
新しいルールクラス()
{
結合 = "AND"、
条件 = "="、
フィールド = "IncidentNumber"、
値 = "10001"
}
};
FRSHEATIntegrationSearchResponse searchResponse = null;
試す
{
searchResponse = frSvc.Search(authSessionKey, tenantId, query);
}
catch (FaultException faultException)
{
MessageFault messageFault = faultException.CreateMessageFault();
if (messageFault.Actor == "SessionExpired")
{
connectresponse = frSvc.Connect(username, password, tenantId, role);
if (connectresponse.connectionStatus == "成功")
{
authSessionKey = connectresponse.sessionKey;
searchResponse = frSvc.Search(connectresponse.sessionKey, tenantId, query);
}
}
}
if (searchResponse != null && searchResponse.status == "Success")
{
WebServiceBusinessObject[][] incidentList = searchResponse.objList;
foreach (WebServiceBusinessObject[]incidentOuterList inincidentList)
{
foreach (WebServiceBusinessObject incident in incidentOuterList)
{
Console.WriteLine("インシデント は選択基準に一致します",incident.FieldValues[0].Value);
}
}
}
特に、次のコード フラグメントに注意してください。試す
{
searchResponse = frSvc.Search(authSessionKey, tenantId, query);
}
catch (FaultException faultException)
{
MessageFault messageFault = faultException.CreateMessageFault();
if (messageFault.Actor == "SessionExpired")
{
connectresponse = frSvc.Connect(username, password, tenantId, role);
if (connectresponse.connectionStatus == "成功")
{
authSessionKey = connectresponse.sessionKey;
searchResponse = frSvc.Search(connectresponse.sessionKey, tenantId, query);
}
}
}
ここでも、Search WebMethod 操作が try-catch ブロック内にラップされていることに注意してください。
ただし、サービス参照の場合、キャッチされる例外は FaultException であり、SOAP 例外ではありません (以前の Web 参照の場合と同様)。
ここで、faultException がキャッチされると、まずそこから MessageFault を取得する必要があります。
MessageFault から、Actor プロパティを検査して、接続エラーがセッション タイムアウトによるものかどうかを判断できます。
再接続ロジックは、前に説明したように、Web 参照ベースのクライアントの場合と同じです。
上記の例は、セッションの有効期限を適切に処理する方法を示しています。 同じ手法は、AccessDenied、InvalidRole などの他の種類の例外を処理する場合にも使用できます。
たとえば、「AccessDenied」例外の場合、Web サービス クライアントはエラーをローカルのログ ファイルに記録したり、クライアントで使用されたユーザ名/パスワードが無効であることを警告する電子メールを管理者に送信したりすることがあります。
ユーザーの役割を取得する
この Web メソッドは、現在の Web サービス ユーザーが使用できるロールのリストを取得します。
この Web メソッドから返される応答オブジェクトには、現在のユーザーの Profile.Employee レコードに関連付けられているロールの配列を格納するフィールドが含まれています。
リクエスト構文:
FRSHEATIntegrationGetRolesResponse GetRolesForUser(string sessionKey, string tenantId)
NameDisplayPair[] GetRolesForUser(文字列セッションキー、文字列テナントID、文字列ユーザ名)
パラメータ:
- sessionKey: 以前の接続要求で受信したキー。
- tenantid: 問題のテナントの ID。
戻り値:
次のように定義される FRSHEATIntegrationGetRolesResponse オブジェクト:
public class FRSHEATIntegrationGetRolesResponse
{
パブリック文字列ステータス { 取得; 設定; }
パブリック リスト<NameDisplayPair> roleList { get; set; }
パブリック文字列例外理由 { 取得; 設定; }
}
FRSHEATIntegrationGetRolesResponse クラスは次のフィールドで構成されます。
- ステータス – このフィールドには、WebMethod が現在のユーザーのロールのリストを正常に取得できたかどうかを示すステータス値が表示されます。 sessionKey (以前の Connect WebMethod 呼び出しから返されたもの) が有効であると仮定すると、このフィールドはほとんどの状況で「Success」という値を返します。
- roleList – NameDisplayPair オブジェクトの配列が含まれます。 各 NameDisplayPair エントリは、現在のユーザーが属するロールに対応します。 配列内の各 NameDisplayPair レコードについて、Name プロパティはロールの名前を返しますが、DisplayName プロパティはロールの DisplayName を返します。
- exceptionReason – GetRolesForUser Web メソッドの実行中に例外がスローされた場合、例外情報はこのフィールドにキャプチャされます。
例
FRSHEATIntegrationGetRolesResponse getRolesResponse = frSvc.GetRolesForUser(authSessionKey, tenantId);
名前表示ペア[] ロールペアリスト = null;
if (getRolesResponse.status == "Success")
{
rolePairList = getRolesResponse.roleList;
Console.WriteLine("現在のユーザーは次のロールに属しています:");
foreach (NameDisplayPair rolePair in rolePairList)
{
Console.WriteLine("\tRole: => DisplayName: \"\"", rolePair.Name, rolePair.DisplayName);
}
}
