--- sourceDocument: Xanadu API リファレンス sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/xanadu/api-reference Release : - xanadu ft:locale : - ja-JP ft:publication_title : - Xanadu API リファレンス ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # ワークプレイスコネクタ Webhook API # ワークプレイスコネクタ Webhook API {#ariaid-title1} * リリースバージョン: Xanadu * * 更新日 2024年08月01日 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：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](https://www.servicenow.com/docs/access?context=configure-workplace-connectors&version=xanadu&pubname=xanadu-employee-service-management&ft:locale=en-US)」を参照してください。 さらに、ハードウェア/センサーベースのイベントペイロードからターゲット ServiceNow テーブル (従業員参加データ \[sn_wsd_wc_employee_attendance_data\] テーブルなど) へのデータ変換/マッピングを定義する拡張ポイントを設定する必要があります。 ワークプレイスコネクタ Webhook の詳細については、「 [Workplace Connectors](https://www.servicenow.com/docs/access?context=workplace-connectors-landing-page&version=xanadu&pubname=xanadu-employee-service-management&ft:locale=en-US)」を参照してください。 ## ワークプレイスコネクタ Webhook - POST /workplace_connector_webhook/event {#ariaid-title2} コネクタイベント \[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 ### サポートされている要求パラメーター {#work_conn_web-POST-event__entry__2}{#work_conn_web-POST-event__version-RESTAPI} | 名前 | 説明 | |-|-| | api_version | オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ：文字列 | [表 : 1. パスパラメーター] {#work_conn_web-POST-event__entry__6} | 名前 | 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\] テーブルにあります。 データタイプ：文字列 | [表 : 2. クエリパラメーター] {#work_conn_web-POST-event__entry__14} | 名前 | Description (説明) | |-|-| | \ | ハードウェア/センサーベースのイベントデータの名前と値のペア。 名前は、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 オブジェクト | [表 : 3. 要求本文パラメーター (XML または JSON)] ### ヘッダー 次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 [サポートされている REST API ヘッダー](https://servicenow-prod.fluidtopics.net/ldF_qFEQnejbeXLBxcUhWg "REST (REpresentational State Transfer) は、Web 上のコンピューターシステム間の標準を提供し、相互の通信を容易にするシンプルなステートレスアーキテクチャです。")」を参照してください。 {#work_conn_web-POST-event__entry__18}{#work_conn_web-POST-event__accept-JSON-only-entry-RESTAPI}{#work_conn_web-POST-event__content_type-JSON-only-entry-RESTAPI} | ヘッダー | 説明 | |-|-| | 承認 | 応答本文のデータフォーマット。application/json のみをサポートします。 | | Content-Type | 要求本文のデータ形式。application/json のみをサポートします。 | [表 : 4. 要求ヘッダー] {#work_conn_web-POST-event__entry__24} | ヘッダー | 説明 | |-|-| | なし | | [表 : 5. 応答ヘッダー] ### ステータスコード この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 [REST API HTTP 応答コード](https://servicenow-prod.fluidtopics.net/ldF_qFEQnejbeXLBxcUhWg "REST (REpresentational State Transfer) は、Web 上のコンピューターシステム間の標準を提供し、相互の通信を容易にするシンプルなステートレスアーキテクチャです。")」を参照してください。 {#work_conn_web-POST-event__table_fqw_2fg_xyb__entry__2}{#work_conn_web-POST-event__entry-200-status-code}{#work_conn_web-POST-event__entry-400-status-code}{#work_conn_web-POST-event__entry-401-status-code}{#work_conn_web-POST-event__entry-404-status-code}{#work_conn_web-POST-event__entry-500-status-code} | ステータスコード | 説明 | |-|-| | 200 | 成功。要求が正常に処理されました。 | | 400 | 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。 | | 401 | 権限がありません。ユーザー資格情報が間違っているか、渡されていません。 | | 404 | 見つかりません。要求アイテムが見つかりませんでした。 | | 500 | 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。 | [表 : 6. ステータスコード] {#work_conn_web-POST-event__table_fqw_2fg_xyb} ### 応答本文のパラメーター {#work_conn_web-POST-event__entry__40} | 名前 | 説明 | |-|-| | エラー | データの処理中に発生したエラーの説明。 データタイプ: オブジェクト "error": { "detail": "String", "message": "String" "status": "String" } | | error.detail | エラーの詳細を示す情報。 データタイプ：文字列 | | error.message | エラーメッセージ データタイプ：文字列 | | status | エンドポイント処理のステータス。 可能な値： * failure:エンドポイントに障害が発生しました。詳細については、 error オブジェクトを参照してください。 * success:エンドポイントが正常に完了しました。レコードが追加されました。 {#work_conn_web-POST-event__ul_lkc_q2g_xyb} データタイプ：文字列 | [ ] ### 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" }