RESTMessageV2 - スコープ対象、グローバル

RESTMessageV2 API には、JavaScript を使用して送信 REST メッセージを送信できるメソッドが用意されています。

この API を使用して、REST プロバイダーから返される応答を管理します。

ユーザーエージェントの値は「ServiceNow/1.0」です。これを変更するには、glide.http.user.agent システムプロパティをシステムのプロパティ [sys_properties] テーブルに追加します。

この API は sn_ws 名前空間で実行されます。

RESTMessageV2 - RESTMessageV2()

空の RESTMessageV2 オブジェクトをインスタンス化します。

この方法でインスタンス化されたオブジェクトを使用する場合は、HTTP メソッドとエンドポイントを手動で指定する必要があります。

表 : 1. パラメーター

名前	タイプ	説明
なし

var sm = new sn_ws.RESTMessageV2();

RESTMessageV2 - RESTMessageV2(文字列 name, 文字列 methodName)

REST メッセージレコードの情報を使用して RESTMessageV2 オブジェクトをインスタンス化します。

このコンストラクターを使用する前に、REST メッセージレコードを定義する必要があります。

表 : 2. パラメーター

名前	タイプ	説明
name	文字列	REST メッセージレコードの名前。
methodName	文字列	使用する HTTP メソッドの名前 (GET/get や PUT/put など。大文字と小文字を区別しない)

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.

RESTMessageV2 - disableForcedVariableSubstitution()

送信 REST メッセージの強制変数代替を無効にします。

注:

要求で中括弧またはドル記号を使用すると、誤って切り捨てられた出力が返される場合があります。要求によって応答が誤って切り捨てられたり、応答が新しい行に分割されたりする場合は、 このコミュニティ記事で 考えられる解決策を参照してください。

表 : 3. パラメーター

名前	タイプ	説明
なし

表 : 4. 返される内容

タイプ	説明
なし

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get");
sm.disableForcedVariableSubstitution();
var response = sm.execute();

RESTMessageV2 - execute()

REST メッセージをエンドポイントに送信します。

表 : 5. パラメーター

名前	タイプ	説明
なし

表 : 6. 返される内容

タイプ	説明
RESTResponse	REST プロバイダーによって返される応答。

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
var response = sm.execute(); //Might throw exception if http connection timed out or some issue with sending request itself because of encryption/decryption of password.

RESTMessageV2 - executeAsync()

REST メッセージを非同期でエンドポイントに送信します。非同期呼び出しを行うときに、インスタンスは Web サービスプロバイダーからの応答を待機しません。

表 : 7. パラメーター

名前	タイプ	説明
なし

表 : 8. 返される内容

タイプ	説明
RESTResponse	REST プロバイダーによって返される応答。

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。executeAsync を使用する場合は、非同期呼び出しを利用して応答本文を別のビジネスルールで処理する方法を検討してください。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
var response = sm.executeAsync(); //Might throw exception if http connection timed out or some issue with sending request itself because of encryption/decryption of password.

RESTMessageV2 - getEndpoint()

REST メッセージのエンドポイントの URL を取得します。

表 : 9. パラメーター

名前	タイプ	説明
なし

表 : 10. 返される内容

タイプ	説明
文字列	REST Web サービスプロバイダーの URL。

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
var endpoint = sm.getEndpoint();

RESTMessageV2 - getRequestBody()

REST メッセージ本文のコンテンツを取得します。

表 : 11. パラメーター

名前	タイプ	説明
なし

表 : 12. 返される内容

タイプ	説明
文字列	REST メッセージの本文。

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
var body = sm.getRequestBody();

RESTMessageV2 - getRequestHeader(文字列 headerName)

REST メッセージで指定された HTTP ヘッダーの値を取得します。

デフォルトでは、このメソッドはシステムによって自動的に設定されたヘッダーの値を返すことはできません。このメソッドにすべてのヘッダーへのアクセスを許可するには、プロパティ glide.http.log_debug を true に設定します。

表 : 13. パラメーター

名前	タイプ	説明
headerName	文字列	値を取得する要求ヘッダー。

表 : 14. 返される内容

タイプ	説明
文字列	指定されたヘッダーの値。

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
var header = sm.getRequestHeader("Accept");

RESTMessageV2 - getRequestHeaders()

REST クライアントによって設定された HTTP ヘッダーと関連する値を取得します。

このメソッドは、システムによって自動的に設定されたヘッダーを返しません。このメソッドがすべてのヘッダーを返すように設定するには、プロパティ glide.http.log_debug を true に設定します。

表 : 15. パラメーター

名前	タイプ	説明
なし

表 : 16. 返される内容

タイプ	説明
オブジェクト	各ヘッダーの名前を関連する値にマッピングするオブジェクト。

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
var headers = sm.getRequestHeaders();

RESTMessageV2 - saveResponseBodyAsAttachment(文字列 tableName, 文字列 recordSysId, 文字列 fileName)

返された応答本文を添付ファイルレコードとして保存するように REST メッセージを設定します。

MID サーバーを介して送信される REST メッセージでこの機能を使用する場合、MID Server ユーザーは、添付ファイルレコードの読み取りと書き込みに必要なロールと、tableName パラメーターで指定されたテーブルでのレコードの読み取りと書き込みに必要なロールを持っている必要があります。

応答本文は、バイナリファイルである必要はなく、添付ファイルとして保存できます。JSON や XML などのテキスト形式を使用した応答本文も保存できます。インスタンスが添付ファイルを保存できない場合は、関連する RESTResponseV2 オブジェクトで getErrorMessage() を呼び出して、エラーの詳細を取得します。

表 : 17. パラメーター

名前	タイプ	説明
tableName	文字列	保存したファイルを添付するレコードを含むテーブルを指定します。
recordSysId	文字列	保存したファイルを添付するレコードの sys_id を指定します。
fileName	文字列	保存するファイルに付けるファイル名を指定します。

表 : 18. 返される内容

タイプ	説明
なし

(function sampleRESTMessageV2() {
  try{
    var request  = new sn_ws.RESTMessageV2();        
    request.setHttpMethod('get');

    var attachment_sys_id  = '<attachment_record_sys_id>', 
      tablename = 'incident',
      recordSysId = '<incident_sys_id>',            
      response,            
      httpResponseStatus,             
      filename ='<filename>';

    //endpoint - ServiceNow REST Attachment API        
    request.setEndpoint('https://<instance_name>.service-now.com/api/now/attachment/' + attachment_sys_id  +'/file');        
    request.setBasicAuth('<username>', '<password>');

    //RESTMessageV2 - saveResponseBodyAsAttachment(String tableName, String recordSysId, String fileName)        
    request.saveResponseBodyAsAttachment(tablename, recordSysId, filename);        

    response = request.execute();        
    httpResponseStatus = response.getStatusCode();  
      
    gs.info(" http response status_code:  " + httpResponseStatus);    
  }
  catch(ex){
    var message  = ex.getMessage();        
    gs.info(message);    
  }
})();

RESTMessageV2 - saveResponseBodyAsAttachment(文字列 tableName, 文字列 recordSysId, 文字列 fileName, 文字列 encryptContext)

返された応答本文を暗号化された添付ファイルレコードとして保存するように REST メッセージを設定します。

MID サーバーを介して送信される REST メッセージでこの機能を使用する場合、MID Server ユーザーは、添付ファイルレコードの読み取りと書き込みに必要なロールと、tableName パラメーターで指定されたテーブルでのレコードの読み取りと書き込みに必要なロールを持っている必要があります。

応答本文は、バイナリファイルである必要はなく、添付ファイルとして保存できます。JSON や XML などのテキスト形式を使用した応答本文も保存できます。インスタンスが添付ファイルを保存できない場合は、関連する RESTResponseV2 オブジェクトで getErrorMessage() を呼び出して、エラーの詳細を取得します。

表 : 19. パラメーター

名前	タイプ	説明
tableName	文字列	保存したファイルを添付するレコードを含むテーブルを指定します。
recordSysId	文字列	保存したファイルを添付するレコードの sys_id を指定します。
fileName	文字列	保存するファイルに付けるファイル名を指定します。
encryptContext	文字列	暗号化コンテキストの sys_id を指定します。保存されたファイルは、このコンテキストを使用して暗号化されます。

表 : 20. 返される内容

タイプ	説明
なし

RESTMessageV2 - setAuthenticationProfile(文字列 type, 文字列 profileId)

既存の基本認証または OAuth 2.0 プロファイルを使用して、REST メッセージの資格情報を設定します。

表 : 21. パラメーター

名前	タイプ	説明
type	文字列	使用する認証プロファイルのタイプ。有効な値は、基本認証を使用する場合は「basic」、OAuth 2.0 を使用する場合は「oauth2」です。
profileId	文字列	認証プロファイルレコードの sys_id。基本認証を使用する場合は、基本認証構成 [sys_auth_profile_basic] レコードの sys_id を指定します。OAuth 2.0 を使用する場合は、OAuth エンティティプロファイル [oauth_entity_profile] レコードの sys_id を指定します。

表 : 22. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var requestBody;
var responseBody;
var status;
var sm;
try{
       // Might throw exception if message doesn't exist or not visible due to scope.
	sm = new sn_ws.RESTMessageV2("<REST_message_record>", "get");  

       //set auth profile to an OAuth 2.0 profile record.
	sm.setAuthenticationProfile('oauth2', '1234adsf123212131123qasdsf'); 

	sm.setStringParameter("symbol", "NOW");
	sm.setStringParameterNoEscape("xml_data","<data>test</data>");

       //In milliseconds. Wait at most 10 seconds for response from http request.
	sm.setHttpTimeout(10000); 
       //Might throw exception if http connection timed out or some issue 
       //with sending request itself because of encryption/decryption of password.
	response = sm.execute();	
       responseBody = response.haveError() ? response.getErrorMessage() : response.getBody();
	status = response.getStatusCode();
} catch(ex) {
	responseBody = ex.getMessage();
	status = '500';
} finally {
	requestBody = sm ? sm.getRequestBody():null;
}

RESTMessageV2 - setBasicAuth(文字列 userName, 文字列 userPass)

REST メッセージの基本認証ヘッダーを設定します。

この方法を使用してセキュリティ値を設定すると、REST メッセージレコードに対して定義された基本認証値が上書きされます。

表 : 23. パラメーター

名前	タイプ	説明
userName	文字列	REST メッセージの認証に使用するユーザー名。
userPass	文字列	指定されたユーザーのパスワード。

表 : 24. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setBasicAuth("username","password");

RESTMessageV2 - setEccCorrelator(文字列 correlator)

送信要求と ECC キュー内の結果の応答レコードを関連付けます。このメソッドは、MID サーバー を介して送信される REST メッセージにのみ適用されます。

提供されたコリレーターは、応答の ECC キューレコードの [エージェントコリレーター] フィールドに入力されます。MID サーバーを介して非同期自動化を設計するときに、それぞれの送信要求に一意のコリレーターを提供して、ECC キュー内の正しい結果を要求に関連付けます。

表 : 25. パラメーター

名前	タイプ	説明
correlator	文字列	一意の識別子

表 : 26. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setEccCorrelator("unique_identifier");

RESTMessageV2 - setEccParameter(文字列 name, 文字列 value)

REST メッセージペイロードに書き込むことで、データベースの値を上書きします。このメソッドは、MID サーバーを介して送信される REST メッセージにのみ適用されます。

エンドポイント URL が REST エンドポイントの最大フィールド長よりも長い場合など、データベース内の REST メッセージにある値が無効な場合は、このメソッドを使用します。ソースを name パラメーターとして渡すことで、このメソッドを使用してエンドポイント URL のみを設定できます。

表 : 27. パラメーター

名前	タイプ	説明
name	文字列	パラメーターの名前 (source など)。
value	文字列	指定されたパラメータに割り当てる値。

表 : 28. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setEccParameter("source","http://very.long.endpoint.url");

RESTMessageV2 - setEndpoint(文字列 endpoint)

REST メッセージのエンドポイントを設定します。

デフォルトでは、REST メッセージは REST メッセージレコードで指定されたエンドポイントを使用します。このメソッドを使用して、このデフォルトを上書きします。パラメーターなしで RESTMessageV2 - RESTMessageV2() コンストラクターを使用する場合は、このメソッドを呼び出す必要があります。

表 : 29. パラメーター

名前	タイプ	説明
endpoint	文字列	連携する REST プロバイダーの URL。

表 : 30. 返される内容

タイプ	説明
なし

var sm = new sn_ws.RESTMessageV2();
sm.setEndpoint("http://web.service.endpoint");

RESTMessageV2 - setHttpMethod(文字列 method)

この REST メッセージが実行する HTTP メソッド (GET や PUT など) を設定します。

パラメーターなしで RESTMessageV2 - RESTMessageV2() コンストラクターを使用する場合は、HTTP メソッドを設定する必要があります。

表 : 31. パラメーター

名前	タイプ	説明
method	文字列	実行する HTTP メソッド。

表 : 32. 返される内容

タイプ	説明
なし

var sm = new sn_ws.RESTMessageV2();
sm.setHttpMethod("post");

RESTMessageV2 - setHttpTimeout(数字 timeoutMs)

要求がタイムアウトするまでに REST メッセージが Web サービスプロバイダーからの応答を待機する時間を設定します。

表 : 33. パラメーター

名前	タイプ	説明
timeoutMs	数字	REST プロバイダーへの呼び出しがタイムアウトするまでの時間 (ミリ秒)。 注: この値はソケットのタイムアウトを設定するものであり、ソケットが指定された時間内にデータを受信しない場合にのみタイムアウトします。応答がストリーミングされる環境では、接続がタイムアウト値よりも長くなる可能性があります。

表 : 34. 返される内容

タイプ	説明
なし

次の例を使用するには、<REST_message_record> をインスタンスからの REST メッセージの名前で置き換えます。

// Might throw exception if message doesn't exist or not visible due to scope.
var sm = new sn_ws.RESTMessageV2("<REST_message_record>", "get");
sm.setHttpTimeout(6000);

RESTMessageV2 - setLogLevel(文字列 level)

このメッセージおよび対応する応答のログレベルを設定します。

RESTMessageV2 API を使用してログレベルを設定すると、REST メッセージレコードで設定されたログレベルが上書きされます。エンドポイントドメインが除外されている場合、またはプロパティ glide.outbound_http_log.override が true の場合、このログレベルは適用されません。送信 Web サービスのログを表示するには、次の場所に移動します。 システムログ > 送信 HTTP 要求.

表 : 35. パラメータ

名前	タイプ	説明
level	文字列	ログレベル。有効な値は、basic、elevated、および all です。

表 : 36. 返される内容

タイプ	説明
なし

var rm = new sn_ws.RESTMessageV2();
rm.setLogLevel('all');

RESTMessageV2 - setMIDServer(文字列 midServer)

MID サーバー を介して通信するように REST メッセージを設定します。

表 : 37. パラメーター

名前	タイプ	説明
midServer	文字列	使用する MID サーバー の名前。インスタンスには、名前が指定されたアクティブな MID サーバー が必要です。

表 : 38. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setMIDServer("mid_server_name");

RESTMessageV2 - setMutualAuth(文字列 profileName)

REST メッセージの相互認証プロトコルプロファイルを設定します。

このメソッドを使用してプロトコルプロファイルを設定すると、REST メッセージレコードに対して選択されたプロトコルプロファイルが上書きされます。

表 : 39. パラメーター

名前	タイプ	説明
profileName	文字列	相互認証に使用するプロトコルプロファイルの名前。

表 : 40. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setMutualAuth("mutual_auth_profile_name");

RESTMessageV2 - setQueryParameter(文字列 name, 文字列 value)

name=value の形式で要求 URL の末尾にパラメーターを追加します。

たとえば、setQueryParameter("sysparm_query","active=true^ORDERBYnumber^ORDERBYDESCcategory"); というコードは、sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory というテキストを要求 URL に追加します。

表 : 41. パラメーター

名前	タイプ	説明
name	文字列	渡す URL パラメーターの名前。
value	文字列	URL パラメーターに割り当てる値。

表 : 42. 返される内容

タイプ	説明
なし

var sm = new sn_ws.RESTMessageV2();
//Set up message, including endpoint and authentication
sm.setQueryParameter("sysparm_query","active=true^ORDERBYnumber^ORDERBYDESCcategory");

RESTMessageV2 - setRequestBody(文字列 body)

PUT または POST HTTP メソッドを使用するときに Web サービスプロバイダーに送信する本文のコンテンツを設定します。

この方法を使用して本文のコンテンツを設定すると、本文の変数が REST メッセージ関数レコードのパラメーターに置き換えられません。REST メッセージ本文内のすべての値を明示的に定義する必要があります。

表 : 43. パラメーター

名前	タイプ	説明
body	文字列	送信する要求の本文。

表 : 44. 返される内容

タイプ	説明
なし

var sm = new sn_ws.RESTMessageV2("Update user","post"); //Might throw exception if message doesn't exist or not visible due to scope.
var body = "<Message body content>";
sm.setRequestBody(body);

RESTMessageV2 - setRequestBodyFromAttachment(文字列 attachmentSysId)

既存の添付ファイルレコードを使用して要求本文を設定します。

MID サーバー を介して送信される REST メッセージでこの関数を使用する場合、添付ファイルレコードを読み取るために必要なロールを MID サーバー ユーザーが持っている必要があります。

表 : 45. パラメーター

名前	タイプ	説明
attachmentSysId	文字列	この REST メッセージで送信する添付ファイル [sys_attachment] レコードの sys_id。

表 : 46. 返される内容

タイプ	説明
なし

(function sampleRESTMessageV2() {
    try {
        var request = new sn_ws.RESTMessageV2();
        request.setHttpMethod('post');
        request.setEndpoint('<web service endpoint URL>');
        request.setRequestBodyFromAttachment('<attachment sys_id>');
        
        var response = request.execute();
        var httpResponseStatus = response.getStatusCode();
      
        gs.info("http response status_code: " + httpResponseStatus);        
    }
    catch (ex) {
        var message = ex.getMessage();
        gs.info(message);
    }
})();

RESTMessageV2 - setRequestHeader(文字列 name, 文字列 value)

REST メッセージ内の HTTP ヘッダーを指定された値に設定します。

表 : 47. パラメーター

名前	タイプ	説明
name	文字列	ヘッダーの名前。
value	文字列	指定されたヘッダーに割り当てる値。

表 : 48. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setRequestHeader("Accept","Application/json");

RESTMessageV2 - setRequestorProfile(文字列 requestorContext, 文字列 requestorId)

別の要求者に関連付けられた OAuth アクセストークンを取得するために、REST メッセージのデフォルトの要求者プロファイルを上書きします。

このメソッドは、OAuth 2.0 認証を使用するように設定された REST メッセージにのみ適用されます。このメソッドはオプションであり、ほとんどの構成では不要です。

表 : 49. パラメーター

名前	タイプ	説明
requestorContext	文字列
requestorId	文字列

表 : 50. 返される内容

タイプ	説明
なし

RESTMessageV2 - setStringParameter(文字列 name, 文字列 value)

REST メッセージレコードの、指定の名前の REST メッセージ関数の変数を、指定した値に設定します。

値の中の XML 予約文字は、同等のエスケープ文字に変換されます。setStringParameterNoEscape を使用して、XML 予約文字をエスケープせずに変数を設定します。

表 : 51. パラメーター

名前	タイプ	説明
name	文字列	REST メッセージ変数の名前。このパラメーターを REST メッセージ レコードで定義してから、値を割り当てる必要があります。
value	文字列	変数に割り当てる値。

表 : 52. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setStringParameter("s","NOW");

RESTMessageV2 - setStringParameterNoEscape(文字列 name, 文字列 value)

REST メッセージレコードの、指定の名前の REST メッセージ関数の変数を、指定した値に設定します。

このメソッドは setStringParameter と同等ですが、XML 予約文字をエスケープしません。

表 : 53. パラメーター

名前	タイプ	説明
name	文字列	REST メッセージ変数の名前。このパラメーターを REST メッセージ レコードで定義してから、値を割り当てる必要があります。
value	文字列	変数に割り当てる値。

表 : 54. 返される内容

タイプ	説明
なし

次の例では、REST_message_record をインスタンスからの REST メッセージの名前で置き換えます。

var sm = new sn_ws.RESTMessageV2("<REST_message_record>","get"); //Might throw exception if message doesn't exist or not visible due to scope.
sm.setStringParameterNoEscape("s","NOW");