ユーザーを取得するデータストリームアクションの作成

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

    • SaaS アプリケーションからユーザーサブスクリプションのリストを取得するデータストリームアクションを作成します。

    始める前に

    既存の ServiceNow® 統合ハブ スポークを使用している場合は、スポークを作成する代わりに使用できるユーザーのリストを取得するデータストリームアクションがあるかどうかを確認します。

    データストリームアクションの詳細については、「 データストリームアクション」を参照してください。

    必要なロール：flow_designer または admin

    手順

    1. 移動先 すべて > Flow Designer > デザイナー.
    2. [ 新規 ] をクリックし、[ データストリーム] を選択します。
    3. フォームのフィールドに入力します。
      表 : 1. アクションプロパティフォーム
      フィールド 値
      名前 任意の名前。たとえば、[ ユーザーを取得] などです。
      アクセス可能 すべてのアプリケーションスコープ。
      カテゴリ このフィールドは空のままにします。
      保護 なし。
      アプリケーション SaaS アプリケーションと統合するスポークアプリ。このスポークアプリは、既存の 統合ハブ スポークでも、自分で作成した新しいスポークでもかまいません。
      インフロー注釈 このフィールドは空のままにします。
      説明 選択内容の説明。
    4. [送信] をクリックします。
    5. 使用している API が要求にユーザー認証を必要とする場合は、「アクション・アウトライン」で 「入力 」をクリックし、認証用の入力を追加します。
      一般的なユーザー認証入力の例は、管理者ユーザー ID とサイト名です。特定のケースでのユーザー認証の要件については、選択した API のドキュメントを参照してください。API がアクセストークンを必要とする場合は、 後で認証情報の値 変数が自動的に作成されます。アクセストークンを入力として追加する必要はありません。

      完了したデータストリームアクションをサブフローで使用する場合は、これらの入力として渡す値を定義します。

    6. 「アクション・アウトライン」の 「要求 」をクリックします。
    7. フォームのフィールドに入力します。
      表 : 2. [要求] フォーム
      フィールド 値
      データをどのように取得しますか。 [REST ステップ] または [SOAP ステップ] を選択します。どちらを選択するかは、統合する SaaS アプリケーションの API によって異なります。
      ページネーションを有効化 選択済み。
      各要求の前にスクリプトを実行 未選択。
    8. [アクションアウトライン] の [ページネーション設定] ステップ をクリックします。
    9. SaaS API で使用されるクエリパラメーターに基づいてページネーション変数を定義します。

      オフセットベースのページネーションを使用している場合は、制限/オフセットページネーションテンプレートを使用して、ページネーション設定をプリロードします。

      注:
      予約済みの getNextPage 変数の値によって、結果の別のページを要求するかどうかが決まります。getNextPage 変数が true である限り、アクションは次のページの要求を送信し続けます。
    10. ページネーション変数を更新するページネーション変数スクリプトを記述します。

      スクリプトは要求ごとに実行されます。ページネーションテンプレートを使用している場合は、必要に応じてプリロードされたスクリプトを調整します。

      次の画像は、ページネーション設定手順の完了した例を示しています。この例は、[サブスクリプションをダウンロード] サブフローで使用される Webex [ユーザーを取得] データストリームアクションからのものです。

      ページネーションセットアップステップ
      注:
      ページネーション変数は、文字列データ型のみをサポートします。数式演算を実行するには、値を整数に変換して必要な操作を実行し、文字列に変換する必要があります。
    11. データの取得方法について選択したオプションに応じて、[アクションアウトライン] で [ SOAP ステップ ] または [REST ステップ ] をクリックします。
    12. [SOAP ステップ] を選択した場合は、次のようにフォームに入力します。
      表 : 3. SOAP ステップフォーム
      フィールド 値
      接続の詳細
      接続 接続エイリアスを使用。
      接続エイリアス 統合プロファイルを作成したときに作成した接続エイリアス。統合プロファイルをまだ作成していない場合は、手順に従って接続 エイリアスを使用してカスタム統合プロファイルを作成します。
      エンドポイント この値は、接続エイリアスを選択すると自動的に入力されます。エイリアスにリンクされた HTTP(s) 接続レコードからの接続 URL に設定されます。
      要求の詳細
      エンベロープの作成 手動で。
      SOAP アクション すべてのユーザーのリストを取得するための API 要求。選択した API のドキュメントを参照して、適切な要求を選択してください。
      SOAP エンベロープ すべてのユーザーのリストを取得するための XML 要求メッセージ。XML 要求メッセージの記述方法については、選択した API のドキュメントを参照してください。一般に、ヘッダーには、ユーザー認証用の入力変数と、アクセストークンとしての 認証情報値 変数が必要です。本文には、ページネーションセットアップステップからすべてのユーザーと変数のリストを取得する要求を含める必要があります。
      注:
      SOAP エンベロープの例については、「サブスクリプションのダウンロード」サブフローで使用される Webex 「ユーザーデータストリームを取得」アクションを参照してください。
    13. [REST ステップ] を選択した場合は、次のようにフォームに入力します。
      表 : 4. REST ステップフォーム
      フィールド 値
      接続の詳細
      接続 接続エイリアスを使用。
      接続エイリアス 統合プロファイルを作成したときに作成した接続エイリアス。統合プロファイルをまだ作成していない場合は、手順に従って接続 エイリアスを使用してカスタム統合プロファイルを作成します。
      ベース URL この値は、接続エイリアスを選択すると自動的に入力されます。エイリアスにリンクされた HTTP(s) 接続レコードからの接続 URL に設定されます。
      要求の詳細
      ビルド要求 手動で。
      リソース パス リソースへのパス。この値はベース URL に追加されます。リソースパスの構築方法については、使用している API のドキュメントを参照してください。
      HTTP メソッド GETです。
      クエリ パラメーター ページネーションのパラメーターを追加します。ページネーションセットアップステップで作成した変数として値を設定します。

      次の画像は、REST ステップの完成した例を示しています。この例は、[サブスクリプションをダウンロード] サブフローで使用される Jira [ユーザーを取得Jira] データストリームアクションからのものです。

      REST ステップ
    14. 「アクション・アウトライン」の「 解析 」をクリックします。
    15. フォームのフィールドに入力します。
      表 : 5. フォームを解析中
      フィールド 値
      各レコードをどのように識別しますか。 JSON/XML スプリッター
      各アイテムをどのように解析してオブジェクトにしますか。 スクリプトパーサー
    16. 「アクション・アウトライン」の 「スプリッター・ステップ 」をクリックします。
    17. フォームのフィールドに入力します。
      表 : 6. スプリッターステップ
      フィールド 値
      ソースフォーマット API 応答によって返される形式に応じて、[XML] または [JSON] を選択します。
      アイテムパス 応答メッセージ内のユーザー要素への絶対パス。応答メッセージの形式については、使用している API のドキュメントを参照してください。
      • XML アイテムパスの例: /message/body/user
      • JSON アイテムパスの例: $.data.user
    18. 「アクション・アウトライン」の 「出力 」をクリックします。
    19. 「 出力の作成 」をクリックし、変数を図のように編集します。
      表 : 7. アクションの出力
      ラベル 名前 タイプ 必須
      targetObject targetObject オブジェクト いいえ
    20. 応答メッセージで返されたユーザーの子要素に基づいて、 targetObject の子アイテムを追加します。
      たとえば、XML 応答は次のようになります。
      <message>​
  <body>​
    <user>
      <userID>​12345</userID>​
      ​<email>​email@email.com</email>​
      <firstName>​Jane</firstName>​
      <lastName>​Doe</lastName>​
      <lastLoginTime>​08/13/2019 20:08:16</lastLoginTime>​
      <active>​TRUE</active>​
    </user>​
    <user>
      ...
    </user>
  </body>​
</message>
      この応答に対して、次のように子アイテムを追加します。
      表 : 8. targetObject の子アイテム
      ラベル 名前 タイプ 必須
      userID userID 文字列 いいえ
      メール メール 文字列 いいえ
      firstName firstName 文字列 いいえ
      lastName lastName 文字列 いいえ
      lastLoginTime lastLoginTime 文字列 いいえ
      active active True/False いいえ
    21. [アクションアウトライン] の [スクリプトパーサー] ステップ をクリックします。
    22. 応答のユーザー要素ごとに targetObject 出力オブジェクトを作成し、各 user 子要素を targetObject 子項目にマップします。

      パーサースクリプトは、ユーザー要素ごとに実行されます。

      注:
      これらの例は、ユーザー取得要求への応答に通常含まれる要素の種類を示しています。これらのスクリプトを直接コピーしないでください。使用している API のドキュメントの要素名を使用します。
      XML 応答を解析するスクリプトの例。 
      (function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.userID = xmlDoc.getNodeText('/user/userID');
    outputs.targetObject.email = xmlDoc.getNodeText('/user/email');
    outputs.targetObject.firstName = xmlDoc.getNodeText('/user/firstName');
    outputs.targetObject.lastName = xmlDoc.getNodeText('/user/lastName');
    outputs.targetObject.lastLoginTime = xmlDoc.getNodeText('/user/lastLoginTime');
    outputs.targetObject.active = xmlDoc.getNodeText('/user/active');
})(inputs, outputs)
      JSON 応答を解析するスクリプトの例。 
      (function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.userID = record.userID;
    outputs.targetObject.email = record.email;
    outputs.targetObject.firstName = record.firstName;
    outputs.targetObject.lastName = record.lastName;
    outputs.targetObject.lastLoginTime = record.lastLoginTime;
    outputs.targetObject.active = record.active;
})(inputs, outputs)
    23. データストリームアクションをテストするには、[ テスト] をクリックします。
      1. エラーの詳細については、テスト結果とシステムログを表示します。
        システムログを表示するには、次の場所に移動します。 システムログ > システムログ > すべて.
      2. データストリームアクションにエラーが発生した場合は、正しいエンドポイントを使用していることと、API リクエストとレスポンスが想定どおりに構成されていることを確認してください。
    24. データストリームアクションが期待どおりに機能していることを確認したら、[ 公開] をクリックします。