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

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：10分

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

    始める前に

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

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

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

    手順

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

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

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

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

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

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

      次の画像は、ページネーションセットアップ手順の完了した例を示しています。この例は、 Webex Download Subscriptions サブフローで使用される Get Users データストリームアクションからのものです。

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

      次の画像は、REST ステップの完成した例を示しています。この例は、Jira Download Subscriptions サブフローで使用される Get Jira Users データストリームアクションからのものです。

      REST ステップ
    14. [Action Outline] の [ Parsing ] をクリックします。
    15. フォームのフィールドに入力します。
      表 : 5. フォームを解析中
      フィールド 値
      各レコードをどのように識別しますか。 JSON/XML スプリッター
      各アイテムをどのように解析してオブジェクトにしますか。 スクリプトパーサー
    16. [Action Outline] の [ Splitter step] をクリックします 。
    17. フォームのフィールドに入力します。
      表 : 6. スプリッターステップ
      フィールド 値
      ソースフォーマット API 応答によって返される形式に応じて、[XML] または [JSON] を選択します。
      アイテムパス 応答メッセージ内のユーザー要素への絶対パス。応答メッセージの形式については、使用している API のドキュメントを参照してください。
      • XML アイテムパスの例: /message/body/user
      • JSON アイテムパスの例: $.data.user
    18. 「アクション・アウトライン」の 「出力 」をクリックします。
    19. [ Create Output (出力の作成)] をクリックし、変数を次のように編集します。
      表 : 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 出力オブジェクトを作成し、各ユーザーの子要素を 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. データストリームアクションが期待どおりに動作していることを確認したら、[ 公開] をクリックします。