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

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：10分

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

    始める前に

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

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

    手順

    1. 次のように移動する。 All (すべて) > Flow Designer (フローデザイナー) > デザイナー.
    2. [New (新規)] を選択します。
    3. [データストリーム] を選択します。
    4. フォームのフィールドに入力します。
      表 : 1. アクションプロパティフォーム
      フィールド 値
      [Name (名前)] 任意の名前。

      たとえば、「 ユーザーを取得」などです。
      アクセス可能 すべてのアプリケーションスコープ。
      カテゴリ このフィールドは空のままにします。
      保護 なし。
      アプリケーション SaaS アプリケーションと統合するためのスポークアプリ。

      このスポークアプリは、既存の 統合ハブ スポークでも、作成した新しいスポークでもかまいません。
      インフロー注釈 このフィールドは空のままにします。
      説明 任意の説明。
    5. [Submit (送信)] を選択します。
    6. 使用している API が要求に対してユーザー認証を必要とする場合は、[アクションアウトライン] で [ 入力 ] を選択し、認証の入力を追加します。
      一般的なユーザー認証入力の例は、 アドミンユーザー ID と サイト名です。特定のケースでのユーザー認証の要件については、選択した API のドキュメントを参照してください。 API がアクセストークンを必要とする場合、 認証情報の値 変数は後で自動的に作成されます。アクセストークンを入力として追加する必要はありません。

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

    7. [アクションアウトライン] で [要求 ] を選択します。
    8. フォームのフィールドに入力します。
      表 : 2. [要求] フォーム
      フィールド Value (値)
      データをどのように取得しますか。 REST ステップまたは SOAP ステップのいずれかを選択します。

      どちらを選択するかは、統合する SaaS アプリケーションの API によって異なります。
      ページネーションを有効化 選択済み。
      各要求の前にスクリプトを実行 選択されていません。
    9. [アクションアウトライン] で ページネーションセットアップステップ を選択します。
    10. SaaS API で使用されるクエリパラメーターに基づいてページネーション変数を定義します。

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

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

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

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

      ページネーションセットアップステップ
      注:
      ページネーション変数は、文字列データ型のみをサポートします。数式演算を実行するには、値を整数に変換して必要な操作を実行し、文字列に変換する必要があります。
    12. データを受信するアクションアウトラインで SOAP ステップ または REST ステップ を選択します。
      • SOAP ステップを選択した場合は、詳細を入力します。
        表 : 3. SOAP ステップフォーム
        フィールド Value (値)
        接続の詳細
        接続 接続エイリアスを使用。
        接続エイリアス 統合プロファイルの作成時に作成した接続エイリアス。統合プロファイルをまだ作成していない場合は、手順に従って、 接続エイリアスを使用してカスタム統合プロファイルを作成します。
        エンドポイント この値は、接続エイリアスを選択すると自動的に入力されます。

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

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

        REST ステップ
    13. [アクションアウトライン] で [ 解析 ] を選択します。
    14. フォームのフィールドに入力します。
      表 : 5. 解析フォーム
      フィールド Value (値)
      各レコードをどのように識別しますか。 JSON/XML スプリッター
      各アイテムをどのように解析してオブジェクトにしますか。 スクリプトパーサー
    15. [アクションアウトライン] で [スプリッターステップ ] を選択します。
    16. フォームのフィールドに入力します。
      表 : 6. スプリッターステップ
      フィールド Value (値)
      ソースフォーマット API 応答によって返された形式に応じて、 XML または JSON を選択します。
      アイテムパス 応答メッセージ内のユーザー要素への絶対パス。応答メッセージの形式については、使用している API のドキュメントを参照してください。
      • XML アイテムパスの例: /message/body/user
      • JSON アイテムパスの例: $.data.user
    17. [Action Outline (アクションアウトライン)] で [Outputs (出力)] を選択します。
    18. [ 出力の作成 ] を選択し、次のように変数を編集します。
      表 : 7. アクションの出力
      ラベル 名前 タイプ Required (必須)
      targetObject targetObject オブジェクト いいえ
    19. 応答メッセージで返されたユーザーの子要素に基づいて、 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 の子アイテム
      ラベル 名前 タイプ Required (必須)
      userID userID 文字列 いいえ
      メール メール 文字列 いいえ
      firstName firstName 文字列 いいえ
      lastName lastName 文字列 いいえ
      前回のログイン時刻 前回のログイン時刻 文字列 いいえ
      アクティブ アクティブ True/False いいえ
    20. [アクションアウトライン] で [スクリプトパーサーステップ ] を選択します。
    21. 応答内のユーザー要素ごとに targetObject 出力オブジェクトを作成し、各ユーザーの子要素を 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)
    22. データストリームアクションをテストするには、 [テスト] を選択します。
      1. テスト結果とシステムログを表示して、エラーの詳細を確認します。
        システムログを表示するには、次に移動します: システムログ > システムログ > All (すべて).
      2. データストリームアクションにエラーがある場合は、正しいエンドポイントを使用していること、および API 要求と応答が想定どおりに構造化されていることを確認してください。
    23. データストリームアクションが期待どおりに機能していることを確認したら、[ 公開] を選択します。

    次のタスク

    ユーザーを取得するためのサブフローの作成.