ワークプレイスコネクタ Webhook API

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

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

    この API は sn_wsd_wc 名前空間で実行されます。この API にアクセスするには、ワークプレイスコネクタ (com.sn_wsd_wc) プラグインをアクティブ化する必要があります。

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

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

    ワークプレイスコネクタ 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. クエリパラメーター
    名前 Description (説明)
    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)
    名前 Description (説明)
    <payload> ハードウェア/センサーベースのイベントデータの名前と値のペア。

    名前は、BadgingDataHandler 拡張ポイントで識別される名前に対応している必要があります。

    例：

    {
  "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"
}