職場ハードウェア関連コネクタ Webhook API

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

    • Workplace Connector Webhook API は、さまざまな種類の職場ハードウェアまたはセンサー (バッジシステムや占有センサーなど) からのデータを Workplace Service Delivery テーブルに保存できるようにする汎用インターフェイスです。

    この API は sn_wsd_wc 名前空間で実行されます。この API にアクセスするには、Workplace Connector (com.sn_wsd_wc) プラグインを有効にする必要があります。

    この API を呼び出す前に、コネクタ構成 [sn_wsd_wc_connector_config] テーブルとプロバイダー構成 [sn_wsd_wc_provider_config] テーブルのレコードを設定する必要があります。これらのレコードの設定方法については、「」を参照してください Configure Workplace Connectors。

    さらに、ハードウェア/センサーベースのイベントペイロードから従業員参加データ [sn_wsd_wc_employee_attendance_data] テーブルなどのターゲット ServiceNow テーブルへのデータ変換/マッピングを定義する拡張ポイントを設定する必要があります。

    職場ハードウェア関連コネクタ Webhook の詳細については、「」を参照してください Workplace Connectors。

    職場ハードウェア関連コネクタ Webhook - POST /workplace_connector_webhook/event

    コネクタイベント [sn_wsd_wc_connector_events] テーブルにレコードを作成し、エンドポイントのペイロードに渡されたハードウェア/センサーベースのイベントデータをそのレコードのペイロードフィールドに保存します。

    エンドポイントはペイロードを保存すると、[コネクタイベント] レコード内の [ステータス] フィールドを 新規に設定し、ペイロードが処理されていないことを示します。

    スケジュール設定済みジョブは、コネクタイベントテーブル内の新しいバッジレコードを検索し、それらを従業員参加データ [sn_wsd_wc_employee_attendance_data] テーブルに変換して書き込みます。[状態] フィールドは [処理済み] に設定されます。

    コネクタイベントレコードのペイロードデータと従業員参加データレコードの間のデータのマッピングは、拡張ポイントで定義されます。この拡張ポイントは、関連するコネクタ構成 [sn_wsd_wc_connector_config] テーブルの [拡張ポイントの定義] フィールドで識別されます。このエンドポイントでは、これは BadgingDataHandler 拡張ポイントです。

    注:
    処理済みステータスのコネクタイベントテーブルのレコードは、作成日から 2 日後に消去されます。エラーステータスのレコードは、作成日から 7 日後に削除されます。新しいステータスのレコードが消去されることはありません。

    URL 形式

    バージョニングされた URL:/ api/sn_wsd_wc/v1/workplace_connector_webhook/event

    デフォルトの URL:/ api/sn_wsd_wc/workplace_connector_webhook/event

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    表 : 2. クエリパラメーター
    名前 説明
    ni.nolog.id 必須です。イベント情報を生成したハードウェアに関連付けられたプロバイダー構成レコードのSys_id。プロバイダー構成 [sn_wsd_wc_provider_config] テーブルにあります。

    データタイプ：文字列
    token_name セキュリティ トークンを識別するユーザー名やその他の値など、セキュリティ トークンの名前。要求の認証に使用されます。プロバイダー構成 [sn_wsd_wc_provider_config] テーブルにあります。

    データタイプ：文字列
    token_value パスワードなどのセキュリティトークンに関連付けられた値。要求の認証に使用されます。プロバイダー構成 [sn_wsd_wc_provider_config] テーブルにあります。

    データタイプ：文字列
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    <ペイロード> ハードウェア/センサーベースのイベントデータの名前と値のペア。

    名前は、バッジデータハンドラー拡張ポイントで識別される名前に対応している必要があります。

    たとえば、次のようになります。

    {
  "Time zone": "(UTC-08:00) Pacific Time (US & Canada)",
  "Event": "Access granted",
  "Door": "L_SJC005_B1.101_ELEVATOR 2 INT",
  "Side": "Reader - In",
  "Cardholder": "ninat.salem",
  "First name": "Nina T",
  "Last name": "Salem",
  "Credential": " ninat.salem's credential",
  "Employee ID (Cardholder)": "10097",
  "Event timestamp": "11/07/2022 00:56:57"
}

    1 回のエンドポイント呼び出し内で複数のイベントのデータを渡すことができます。各イベントのデータを個別のオブジェクトで渡します。各イベントのデータは、個別の従業員参加データレコードに保存されます。

    注:
    日付解析の問題を回避するために、指定されたタイムスタンプが ISO 8601 形式に準拠していることを確認してください。

    データタイプ:JSON オブジェクト

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    Content-Type 要求本文のデータ形式。application/json のみをサポートします。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    404 見つかりません。要求アイテムが見つかりませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

    応答本文のパラメーター

    名前 説明
    エラー データの処理中に発生したエラーの説明。

    データタイプ: オブジェクト

    "error": {
  "detail": "String",
  "message": "String"
"status": "String"
}
    error.detail エラーの詳細を示す情報。

    データタイプ：文字列
    error.message エラーメッセージ

    データタイプ：文字列
    status エンドポイント処理のステータス。
    可能な値：
    • failure:エンドポイントが失敗しました。詳細については、 error オブジェクトを参照してください。
    • success:エンドポイントが正常に完了しました。レコードが追加されました。

    データタイプ：文字列

    cURL 要求

    次のコード例は、このエンドポイントを呼び出して、複数のカードリーダーイベントをコネクタイベントテーブルに追加する方法を示しています。要求を処理する前に、要求は認証されます。

    curl http://instance.servicenow.com/api/sn_wsd_wc/v1/workplace_connector_webhook/event?token_name=token&ni.nolog.id=8e666cb0a3053110bc6e146546fcdad1&token_value=babugosha  \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data --data "{
  \"Time zone\": \"(UTC+02:00) Jerusalem\",
  \"Event\": \"Access granted\",
  \"Door\": \"L_TLV001_A3.07_KITCHEN AREA INT\",
  \"Side\": \"Reader - In\",
  \"Cardholder\": \" ninat.alem\",
  \"First name\": \" Nina T\",
  \"Last name\": \" Salem\",
  \"Credential\": \" ninat.salem's credential\",
  \"Employee ID (Cardholder)\": 10097,
  \"Event timestamp\": \"11/07/2022 10:57:24\"
}
{
  \"Time zone\": \"(UTC+02:00) Jerusalem\",
  \"Event\": \"Access granted\",
  \"Door\": \"L_TLV003_A4.07_FRONT ENT\",
  \"Side\": \"Reader - In\",
  \"Cardholder\": \" joe.blue\",
  \"First name\": \" Joe\",
  \"Last name\": \" Blue\",
  \"Credential\": \" joe.blue's credential\",
  \"Employee ID (Cardholder)\": 24098,
  \"Event timestamp\": \"11/07/2022 10:59:33\"
}"

    応答：

    // Successful response
{
  "staus": "success"
}

// Error response
{
  "error": {
    "message": "Events request is invalid. Events query parms incomplete, some fields are missing",
    "detail": "Missing fields: token_name, token_value"
  }
  "status": "failure"
}