Connect Webメソッドの使用
認証と承認の両方の操作を実行し、ユーザーが適切に認証され、指定されたロールに属していることを確認します。
リクエスト構文
FRSHEATIntegrationConnectionResponse Connect(string userName, string password, string tenantId, string role)パラメータ
- userName: セッションが作成されるログイン ID。 Web メソッドは、 Profile.Employee ビジネス オブジェクト (プロファイル テーブル) の LoginID 列でログイン ID を検索します。
- パスワード: ユーザーのパスワード。 これは、従業員レコードの構成に応じて、内部パスワードまたは外部 (アクティブ ディレクトリ) パスワードのいずれかになります。
- tenantId: セッションが作成されるテナント。 Web メソッドは、 サービス マネージャ構成データベース (ConfigDB と呼ばれます) 内のテナントのビジネス オブジェクトの TenantURL フィールドでテナント ID を検索します。 認証が成功するには、テナント レコードが アクティブ 状態である必要があります。
- ロール: ユーザーがログインするロール。
戻り値
FRSHEATIntegrationConnectionResponse クラスは次のように定義されます。
パブリッククラス FRSHEATIntegrationConnectionResponse
{
パブリック文字列 connectionStatus;
パブリック文字列セッションキー;
パブリック文字列 exceptionReason;
}FRSHEATIntegrationConnectionResponse クラスには次のフィールドがあります。
- connectionStatus: 接続の状態に関するステータスを提供します。 下の表には、 使用可能なステータス値の説明。
- sessionKey: 以降のすべての Web サービス操作で使用するセッション キー。 このフィールドは、 connectionStatus パラメータの値が successの場合にのみ入力されます。 それ以外の場合、値は null になります。
- exceptionReason: この Web メソッドの実行時にアプリケーションが例外をスローした場合の例外情報が含まれます。
Connect Web メソッドが正常に完了すると、アプリケーションはセッション キーを FRSHEATIntegrationConnectiontResponse オブジェクト内の対応するメンバーに保存します。
例外
Connect Web メソッド操作中 (認証フェーズまたは承認フェーズ中) にエラーが発生した場合、サーバーは SOAP 例外をスローし、Web サービス クライアントは例外を処理する必要があります。
次の表は、 Connect Web メソッドの実行時に発生する可能性のある例外を示しています。
SOAP例外 | 説明 | アクション |
|---|---|---|
アクセスが拒否されました | 指定されたユーザ名がテナント内に存在しないか、または指定されたパスワードがユーザ名に対して無効です。 | 資格情報が正しく指定されていることを確認してください。 |
テナントが見つかりません | 指定されたテナント URL が見つからないか、テナントが現在 アクティブ ステータスではありません。 | テナントにアクセスするためのテナント URL が正しいことを確認します。 そうであれば、このテナントのステータスについて Ivanti にお問い合わせください。 |
メンテナンス中のテナント | 指定されたテナントは現在メンテナンス モードです。 | テナントがメンテナンス モードになっていることを確認します。 そうであれば、テナントがいつアクティブ状態に戻るかについて Ivanti に問い合わせてください。 |
無効な役割 | 指定されたロール定義がテナントで使用できないか、ユーザーが現在指定されたロールに関連付けられていません。 | ロールがテナントに存在し、ユーザーが指定されたロールに属していることを確認します。 |
セッション期限切れ | セッション キーは期限切れのセッションを参照します。 これは通常、API 操作が以前の Connect Web メソッド呼び出しからのセッション キーを使用し、非アクティブのためにセッションが期限切れになった場合に発生します。 | 新しいセッション キーを取得するには、 Connect Web メソッドを再度実行します。 |
他の Web メソッドを実行するときに同じセッション キーを使用すると、認証または承認エラーが発生する可能性があります。 Web サービス クライアントは、追加の Web メソッドを実行するときに接続が失敗する可能性を考慮する必要があります。
例
FRSHEATIntegration frSvc = new FRSHEATIntegration();
FRSHEATIntegrationConnectionResponse connectresponse = frSvc.Connect(username, password, tenantId, role);
if (connectresponse.connectionStatus == "Success")
{
...
}セッションの有効期限の処理
セッション キーを取得するために Connect Web メソッドを最初に呼び出した後、通常、Web サービス クライアントは後続の Web メソッドで同じセッション キー値を再利用します。
Web サービス クライアントがセッション タイムアウト値よりも長くアイドル状態になると、セッションが期限切れになり、セッション キーは無効になります。 セッションの有効期限が切れた後、有効期限が切れたセッション キーを再度使用しようとすると、サーバーはセッションの有効期限が切れたことを示す SOAP 例外を返します。 明示的な SOAP 例外をクライアントに返すことで、クライアントは標準の例外処理手法を使用して Connect Web メソッドを再度呼び出し、後続の Web メソッドで使用する新しいセッション キーを取得できます。
.NET ベースの Web サービス クライアントの場合、Web 参照またはサービス参照のいずれかを使用して FRSHEATIntegration API を参照できます。 SOAP 例外を処理するコードは、参照の種類によって若干異なります。
次のコードは、Web サービス クライアントが FRSHEATIntegration API への Web 参照を使用して定義されている場合に、これを実現する方法を示しています。
ObjectQueryDefinition query = new ObjectQueryDefinition();
クエリー.Select = 新しい SelectClass();
FieldClass[] incidentFieldObjects = new FieldClass[] {
new FieldClass()
{
Name = "IncidentNumber",
Type = "Text"
},
new FieldClass()
{
Name = "Service",
Type = "Text"
}
};
クエリー.Select.Fields = インシデントフィールドオブジェクト;
クエリ.From = 新しい FromClass();
query.From.Object = "インシデント";
query.Where = 新しいルールクラス[] {
new RuleClass()
{
Join = "AND",
Condition = "=",
Field = "IncidentNumber",
Value = "10001"
}
};
FRSHEATIntegrationSearchResponse searchResponse = null;
試す
{
searchResponse = frSvc.Search(authSessionKey、テナントID、クエリ);
}
(SoapException soapException) をキャッチします
{
(soapException.Actor == "セッション期限切れ")の場合
{
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 == "成功")
{
WebServiceBusinessObject[][] incidentList = searchResponse.objList;
foreach (WebServiceBusinessObject[]incidentOuterList inincidentList)
{
foreach (incidentOuterList 内の WebServiceBusinessObject インシデント)
{
Console.WriteLine("インシデント {0} は選択基準に一致します",incident.FieldValues[0].Value);
}
}
}特に、次のコード フラグメントに注意してください。
試す
{
searchResponse = frSvc.Search(authSessionKey、テナントID、クエリ);
}
(SoapException soapException) をキャッチします
{
(soapException.Actor == "セッション期限切れ")の場合
{
connectresponse = frSvc.Connect(username, password, tenantId, role);
if (connectresponse.connectionStatus == "成功")
{
authSessionKey = connectresponse.sessionKey;
searchResponse = frSvc.Search(connectresponse.sessionKey, tenantId, query);
}
}
}Search Web メソッド操作が try-catch ブロック内にラップされていることに注意してください。
セッションの有効期限に対応する SOAP 例外が発生した場合は、SOAP 例外の Actor プロパティを確認して、接続エラーがセッション タイムアウトによるものかどうかを判断します。 例外がセッション タイムアウトによるものである場合、アプリケーションは Connect Web メソッドを再度呼び出して、新しいセッション キーを取得します。 authSessionKey パラメータがグローバルにアクセス可能な文字列である場合、アプリケーションは connect response オブジェクトのセッション キー プロパティを更新し、 Search Web メソッドを再度実行できます。
次のコード サンプル/例は、Web サービス クライアントが FRSHEATIntegration API へのサービス参照を使用して定義されている場合を示しています。
ObjectQueryDefinition query = new ObjectQueryDefinition();
query.Select = new SelectClass();
FieldClass[] incidentFieldObjects = new FieldClass[] {
new FieldClass()
{
名前 = "インシデント番号",
タイプ = "テキスト"
},
new FieldClass()
{
名前 = "サービス"、
タイプ = "テキスト"
}
};
query.Select.Fields = incidentFieldObjects;
query.From = new FromClass();
query.From.Object = "Incident";
query.Where = new RuleClass[] {
new RuleClass()
{
結合 = "AND"、
条件 = "="、
フィールド = "IncidentNumber"、
値 = "10001"
}
};
FRSHEATIntegrationSearchResponse searchResponse = null;
試す
{
searchResponse = frSvc.Search(authSessionKey, tenantId, query);
}
キャッチ (FaultException 障害例外)
{
メッセージ エラー messageFault = 障害例外.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 == "成功")
{
WebServiceBusinessObject[][] incidentList = searchResponse.objList;
foreach (WebServiceBusinessObject[]incidentOuterList inincidentList)
{
foreach (incidentOuterList 内の WebServiceBusinessObject インシデント)
{
Console.WriteLine("インシデント {0} は選択基準に一致します",incident.FieldValues[0].Value);
}
}
}特に、次のコード フラグメントに注意してください。
試す
{
searchResponse = frSvc.Search(authSessionKey, tenantId, query);
}
キャッチ (FaultException 障害例外)
{
メッセージ エラー messageFault = 障害例外.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 Web メソッド操作が try-catch ブロック内にラップされていることに注意してください。 ただし、サービス参照の場合、キャッチされる例外は、SOAP 例外ではなく、障害例外になります (以前の Web 参照の場合と同様)。 アプリケーションは、障害例外をキャッチした後、メッセージ障害を取得します。 SOAP 例外の Actor プロパティを確認して、接続エラーがセッション タイムアウトによるものかどうかを判断します。
この例では、セッションの有効期限を適切に処理する方法を示します。 アクセス拒否、無効なロールなど、他の種類の例外を処理する場合にも同じ手法を使用できます。 たとえば、アクセス拒否例外の場合、Web サービス クライアントはエラーをローカルのログ ファイルに記録したり、クライアントで使用されたユーザ名とパスワードが無効であることを管理者に電子メールで通知したりすることがあります。
