REST Web サービスアクティビティを作成する

  • リリースバージョン: Washingtondc
  • 更新日 2024年02月01日
  • 読む17読むのに数分

    • この手順を使用して、カスタム REST Web サービス オーケストレーション アクティビティを作成します。

    始める前に

    必要なロール：web_service_admin、activity_admin、activity_creator

    このタスクについて

    REST Web サービスワークフローアクティビティを作成して使用するには、次の手順を実行します。
    • 適切な REST メッセージがまだ設定されていない場合は作成します。
    • カスタム REST アクティビティを作成または編集する必要があるすべてのユーザーに web_service_admin ロールを割り当てます。
    • このアクティビティのアプリケーションまたはアプリケーションスコープを決定します。
    • アクティビティに使用する REST メッセージの作成を決定します。この値を使用して、REST メッセージで設定されたエンドポイントを上書きします。
    • オプションで基本認証資格情報を作成します。この値を使用して、SOAP メッセージで設定された資格情報を上書きします。

    手順

    1. カスタムアクティビティを作成します。
      このアクションにより、テンプレートを使用してカスタムアクティビティが作成されます。
    2. 一般的なプロパティを設定し、入力変数を作成した後、REST Web サービス実行コマンドを設定します。
      オプション説明
      入力変数をマップする 作成した変数を使用して、オーケストレーションが実行するコマンドを設定します。
      REST メッセージ このアクティビティで使用する既存の REST メッセージの名前。
      REST メッセージ関数 このアクティビティに使用する REST メッセージ関数。
      エンドポイント このアクティビティが使用する REST Web サービスのエンドポイント URL。このフィールドにエンドポイントを入力して、REST メッセージで設定されたエンドポイントを上書きします。ロック アイコンをクリックして、入力フィールドを開きます。
      変数代替 REST エンドポイントに渡す名前と値のペア。これらのパラメーターは手動で作成することも、入力変数をパラメーター フィールドにドラッグして値を割り当てることもできます。REST メッセージ内に定義されている、${} を使用するパラメーターには、このアクティビティテンプレートからデータを割り当てることができます。[追加の属性] 列を使用して、テキストをエスケープしないようにシステムを設定します。デフォルトでは、REST メッセージに送信されるテキストはエスケープされます。ユーザーが送信 REST メッセージの変数代替を使用して REST メッセージ内に変数を入力した場合は、[名前] 列に値が自動的に入力されます。
      追加ヘッダー 選択された REST メッセージの追加の HTTP ヘッダー パラメーター。これらの値を使用して、REST メッセージから継承したパラメーターを上書きすることもできます。
      追加のクエリ パラメーター 選択された REST メッセージの追加のクエリ パラメーター。これらの値を使用して、REST メッセージから継承したパラメーターを上書きすることもできます。
      MID Server を使用 MID Server を使用して REST Web サービスを呼び出す必要があるかどうかを決定するチェック ボックス。
      注:
      REST Web サービスメッセージ関数で MID Server が定義されている場合は、ここで選択した MID Server ではなくその MID Server が使用されます。
      必要な MID Server 機能 REST エンドポイントに接続するための適切な Mid Server 機能を備えた MID Server。デフォルトでは、REST 機能を備えた MID Server が選択されます。このフィールドは、[MID Server を使用] チェック ボックスが選択されている場合に使用可能です。
      タイムアウト タイムアウトになるまでに許容される Rest Web サービス要求の経過時間 (秒単位)。デフォルトは 10 です。
      認証 エンドポイントに必要な認証のタイプを決定します。オプションは次のとおりです。
      • REST メッセージ内の既存の資格情報を使用する：REST メッセージ定義からの資格情報定義を使用します。
      • 基本認証資格情報で上書きする：送信 SOAP での基本認証の有効化資格情報を使用して、REST メッセージ定義内の資格情報を上書きします。基本認証資格情報は、プロビジョニングした後で選択可能になります。
      • 証明書認証資格情報で上書きする：秘密鍵などの資格情報を使用して、REST メッセージ定義内の資格情報を上書きします。
      • 基本認証と証明書認証の両方の資格情報で上書きする：基本認証と証明書認証の両方を使用して、REST メッセージ定義内の資格情報を上書きします。
      • OAuth 認証資格情報で上書きする：OAuth 2.0 資格情報を使用して、REST メッセージ定義内の資格情報を上書きします。このアクティビティに対して選択する REST メッセージには、「OAuth 2.0 チュートリアル：REST メッセージの作成」が [OAuth 2.0] に設定され、その OAuth プロファイルとスコープが適切に設定されている必要があります。
      資格情報 必要な REST エンドポイント基本認証資格情報。このフィールドは、[認証] フィールドで [基本認証資格情報で上書きする] が選択されていると使用可能になります。基本認証資格情報のみが選択リストに表示されます。このリストには、インスタンスに保管されている資格情報と外部ストレージシステムの資格情報 ID が含まれています。CyberArk セーフに保管されている資格情報を使用している場合、MID Server 構成ファイル内に定義されているデフォルトのセーフを上書きできます。詳細については、「CyberArk 用の MID Server の設定」を参照してください。別のセーフの名前をプリフィックスとして、資格情報 ID にコロンで区切って追加します。newsafe:orch-test-f5 など。
      プロトコルプロファイル 使用する資格情報認証。このフィールドは、[認証] の選択項目が [証明書認証資格情報で上書きする] または [基本認証と証明書認証の両方の資格情報で上書きする] のどちらかであると使用可能になります。
      OAuth プロファイル この REST メッセージの OAuth プロバイターのプロファイル。詳細については、「OAuth プロファイルの指定」を参照してください。
      注:
      テストペイロードのパラメーター値を、[出力] タブの変数に自動的にマッピングできます。「出力変数を自動マッピングする」を参照してください。

    次のタスク

    出力変数を作成する、解析ルールを作成する、または条件を作成するのいずれかを行って、Rest Web サービスアクティビティの作成を終了します。テンプレート オプションの詳細については、「カスタムアクティビティを作成する」のトピックを参照してください。

    REST アクティビティ出力変数を自動マッピングする

    ServiceNowアクティビティデザイナーを使用すると、REST テストペイロードのパラメーター値を [出力] ステージの変数に自動的にマッピングできます。

    始める前に

    必要なロール：web_service_admin、activity_admin、activity_creator

    このタスクについて

    注:
    オーケストレーションがエンドポイントに接続してデータを返すのに十分な情報を提供している場合は、アクティビティデザイナーのどのステージからでも入力変数をテストできます。通常、[実行コマンド] ステージが、入力のテストの準備ができているポイントです。

    手順

    1. アクティビティデザイナーでは、[実行コマンド] ステージに進みます。
    2. 必要に応じて、適切な MID Server を定義します。
      MID Server が見つからない場合、またはターゲットに接続できない場合、テストは失敗します。
    3. [アクティビティをテスト] をクリックして、入力パラメーターをテストします。
      パラメーターとフィールドの実際の値を追加した場合、指定したターゲットに対してこれらの値が実行され、結果のペイロードが返されます。入力変数をフィールドとパラメーターにマップした場合、これらの変数にテスト値を割り当てるためのダイアログ ボックスが表示されます。
    4. 必要に応じてテスト値を入力し、[OK] をクリックしてペイロードを表示します。
      [応答] フォームの [Raw 出力] タブに、ペイロード全体が表示されます。
      自動マッピングコントロール
    5. 次の自動マッピング オプションのいずれかを選択します。
      • ローカルに自動マップ：値をアクティビティ内で使用するためにローカル変数に直接マップします。
      • 出力する自動マップ：値を出力変数に直接マッピングして、ワークフロー内の他のアクティビティに渡します。出力変数への自動マッピングによって、オブジェクトのアレイが作成されます。それぞれに、クエリ結果からの列名が含まれます。

    REST テンプレートの実行パラメーター

    実行パラメーターを使用して、アクティビティデザイナーの [前処理] フォームで入力プロセス スクリプトを作成します。

    REST Web サービス コマンド フィールドの説明については、「REST 実行コマンドを設定する」を参照してください。
    注:
    この表のすべての変数で executionParam. プリフィックスを使用する必要があります。
    表 : 1. REST テンプレートの実行パラメーター
    名前 変数 タイプ 使用法
    Web サービスメッセージ web_service_message 参照 対応する Web サービスメッセージの sys_id。
    Web サービスメッセージ関数 web_service_message_function 参照 REST メッセージ関数の sys_id。
    Web サービス エンドポイント web_service_endpoint 文字列 REST エンドポイントの URL。
    パラメーター parameters JavaScript オブジェクトの配列 executionParam. プリフィックスを付けて表現した JavaScript オブジェクトの配列。このパラメーターを使用して配列を作成する方法については、「 REST テンプレートで JavaScript 配列を作成する」を参照してください。
    MID Server を使用 use_mid_server ブーリアン MID Server を使用するかどうかを選択します。値が true である場合は MID Server を使用し、値が false であると MID Server を使用しません。
    MidCapabilities midCapabilities 文字列 (コンマ区切り) 必要な MIDP サーバー機能の参照リスト。
    タイムアウト time-out 文字列 許容タイムアウト時間 (秒単位)。
    ValueCapabilities valueCapabilities ハッシュマップの配列 MID Server の選択に使用される機能値。詳細については、「MID Server の機能」を参照してください。値によって割り当てられる追加機能がある場合、この例を使用して MID Server の選択をカスタマイズします。
    var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability);
    認証タイプ auth-type ブーリアン 使用する資格情報のタイプ以下から選択可能です。
    • basic_auth_pick_credentials
    • use_existing_credentials
    資格情報 credentials 参照 選択されている auth_type が basic_auth_pick_credentials である場合に、この REST メッセージに使用する資格情報が含まれています。

    REST テンプレートで JavaScript 配列を作成する

    以下は、REST 実行パラメーターを使用した JavaScript 配列の作成に関する説明です。

    始める前に

    必要なロール：web_service_admin、activity_admin、activity_creator

    このタスクについて

    パラメーターの配列に名前と値のペアをさらに追加するには、値を既存の配列に追加します。

    手順

    1. 次の構文を使用して JavaScript オブジェクトを作成し、それを executionParam.parameter 配列に追加します。 
      var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; 
executionParam.parameters.push(newParameter);

      新しいパラメーター JavaScript オブジェクトを配列に追加することにより、配列内ですでに利用可能な要素が影響を受けないようにします。

    2. [REST メッセージ パラメーター] 入力フィールドの [追加の属性] 列の値を必ず [テキストをエスケープしない] に設定してください。

      この場合、value 属性に指定された値はエスケープされません。この例は次のとおりです。

      var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; 
executionParam.parameters.push(newParameter);
      注:
      additional_attribute フィールドの値が [なし] の場合、value 属性によって指定された値はエスケープされます。最初の例では、parameterValue がエスケープされます。

    REST テンプレートの後処理パラメーター

    これらのパラメーターを使用して、後処理スクリプトを作成します。

    表 : 2. アクティビティデザイナーの後処理パラメーター
    名前 変数 タイプ 使用法
    ステータスコード status_code 整数 REST Web サービスから返されたステータスコードが含まれます。
    ヘッダー ヘッダー JavaScript オブジェクトのハッシュマップ Web サービスに渡されるヘッダー値と関連付けられたキー値ペアのハッシュマップ。executionResult.header[keyName] を使用してそれぞれの値にアクセスできます。
    本文 本文 文字列 REST メッセージの出力を表す文字列値が含まれます。
    エラー エラー 文字列 エラーがある場合は、REST Web サービスからエラー文字列を返します。エラーがない場合は null を返します。

    REST 実行コマンドを設定する

    作成した入力変数を使用して、オーケストレーションが REST エンドポイントで実行するコマンドを構成します。

    始める前に

    [実行コマンド] ステージに進む前に、[入力] フォームで必要な入力変数を作成します。

    必要なロール：web_service_admin、activity_admin、activity_creator

    注:
    MID Serverとエンドポイント間の REST 接続は、ワークフロー コンテキストでアクティビティを実行しなくてもテストできます。詳細は、「テスト テンプレート出力」を参照してください。

    手順

    1. 入力のリストから変数をドラッグし、コマンド フィールドにドロップします。
      システムによって、コマンドの正しい構文で変数がフォーマットされます。
      図 : 1. REST 実行コマンド
      REST 実行コマンド
    2. 表に示されたフィールドに入力します。
      表 : 3. REST 実行コマンド フィールド
      フィールド 説明
      入力 入力変数ビルダー。入力変数を作成するを実行して、使用可能なフィールドにマップします。
      REST メッセージ このアクティビティで使用する既存の REST メッセージの名前。このフィールドを設定するには、web_service_admin ロールが必要です。
      REST メッセージ関数 このアクティビティに使用する REST メッセージ関数。このフィールドを設定するには、web_service_admin ロールが必要です。
      エンドポイント このアクティビティが使用する REST Web サービスのエンドポイント URL。このフィールドにエンドポイントを入力して、REST メッセージで設定されたエンドポイントを上書きします。ロック アイコンをクリックして、入力フィールドを開きます。
      変数代替 REST エンドポイントに渡す名前と値のペア。これらのパラメーターは手動で作成することも、入力変数をパラメーター フィールドにドラッグ アンド ドロップして値を割り当てることもできます。REST メッセージ内に定義されている、${} を使用するパラメーターには、このアクティビティテンプレートからデータを割り当てることができます。[追加の属性] 列を使用して、テキストをエスケープしないようにシステムを設定します。デフォルトでは、REST メッセージに送信されるテキストはエスケープされます。ユーザーが送信 REST メッセージの変数代替を使用して REST メッセージ内に変数を入力した場合は、[名前] 列に値が自動的に入力されます。
      追加ヘッダー 選択された REST メッセージの追加の HTTP ヘッダー パラメーター。これらの値を使用して、REST メッセージから継承したパラメーターを上書きすることもできます。
      追加のクエリ パラメーター 選択された REST メッセージの追加のクエリ パラメーター。これらの値を使用して、REST メッセージから継承したパラメーターを上書きすることもできます。
      MID Server を使用 MID Server を使用して REST Web サービスを呼び出す必要があるかどうかを決定するチェック ボックス。
      注:
      REST Web サービスメッセージ関数で MID Server が定義されている場合は、ここで選択した MID Server ではなくその MID Server が使用されます。
      必要な MID Server 機能 REST エンドポイントに接続するための適切な Mid Server 機能を備えた MID Server。デフォルトでは、REST 機能を備えた MID Server が選択されます。このフィールドは、[MID Server を使用] チェック ボックスが選択されている場合に使用可能です。
      タイムアウト タイムアウトになるまでに許容される Rest Web サービス要求の経過時間 (秒単位)。デフォルトは 10 です。
      認証 エンドポイントに必要な認証のタイプを決定します。オプションは次のとおりです。
      • REST メッセージ内の既存の資格情報を使用する：REST メッセージ定義からの資格情報定義を使用します。
      • 基本認証資格情報で上書きする：送信 SOAP での基本認証の有効化資格情報を使用して、REST メッセージ定義内の資格情報を上書きします。基本認証資格情報は、プロビジョニングした後で選択可能になります。
      • 証明書認証資格情報で上書きする：秘密鍵などの資格情報を使用して、REST メッセージ定義内の資格情報を上書きします。
      • 基本認証と証明書認証の両方の資格情報で上書きする：基本認証と証明書認証の両方を使用して、REST メッセージ定義内の資格情報を上書きします。
      • OAuth 認証資格情報で上書きする：OAuth 2.0 資格情報を使用して、REST メッセージ定義内の資格情報を上書きします。このアクティビティに対して選択する REST メッセージには、「OAuth 2.0 チュートリアル：REST メッセージの作成」が [OAuth 2.0] に設定され、その OAuth プロファイルとスコープが適切に設定されている必要があります。
      資格情報 必要な REST エンドポイント基本認証資格情報。このフィールドは、[認証] フィールドで [基本認証資格情報で上書きする] が選択されていると使用可能になります。基本認証資格情報のみが選択リストに表示されます。このリストには、インスタンスに保管されている資格情報と外部ストレージシステムの資格情報 ID が含まれています。CyberArk セーフに保管されている資格情報を使用している場合、別のセーフの名前をコロンで区切って資格情報 ID にプリフィックスとして追加することにより、MID Server 構成ファイル内に定義されている CyberArk 用の MID Server の設定を上書きできます。newsafe:orch-test-f5 など。
      プロトコルプロファイル 使用する資格情報認証。このフィールドは、[認証] フィールドの選択項目が [証明書認証資格情報で上書きする] または [基本認証と証明書認証の両方の資格情報で上書きする] のどちらかであると使用可能になります。
      OAuth プロファイル この REST メッセージの OAuth プロバイターのプロファイル。詳細については、「OAuth プロファイルの指定」を参照してください。
    3. [保存] をクリックします。
    4. [続行] をクリックして、[出力] ステージに進みます。