Webhook-API für Arbeitsplatz-Connector
Die Webhook Des Arbeitsplatzverbinders API ist eine generische Schnittstelle, die die Speicherung von Daten aus verschiedenen Arten von Arbeitsplatzhardware oder -Sensoren (z. B. Abzeichensysteme oder Belegungssensoren) in Tabellen für Arbeitsplatzservicebereitstellung ermöglicht.
Diese API wird in ausgeführt sn_wsd_wc Namespace. Um auf diese API zuzugreifen, muss das Plugin „Workplace Connectors“ (com.sn_wsd_wc) aktiviert sein.
Bevor Sie diese API aufrufen, müssen Sie Datensätze in den Tabellen „Connector-Konfiguration“ [sn_wsd_wc_Connector_config] und „Provider-Konfiguration“ [sn_wsd_wc_Provider_config] konfigurieren. Informationen zum Konfigurieren dieser Datensätze finden Sie unter Configure Workplace Connectors.
Darüber hinaus müssen Sie einen Erweiterungspunkt einrichten, der die Datenkonvertierung/-Zuordnung von der Hardware-/sensorbasierten Ereignisnutzlast zum Ziel definiert ServiceNow Tabelle, z. B. die Tabelle „Mitarbeiteranwesenheitsdaten“ [sn_wsd_wc_Employee_Attendance_Data].
Weitere Informationen zu Arbeitsplatzverbinder-Webhooks finden Sie unter Workplace Connectors.
Workplace Connector-Webhook – POST /Workplace_Connector_webhook/event
Erstellt einen Datensatz in der Tabelle „Connector-Ereignisse“ [sn_wsd_wc_Connector_Events] und speichert dann die Hardware-/sensorbasierten Ereignisdaten, die in der Nutzlast des Endpunkts übergeben wurden, im Feld „Nutzlast“ dieses Datensatzes.
Nachdem der Endpunkt die Nutzlast gespeichert hat, wird das Feld Status im Datensatz „Connector-Ereignisse“ auf festgelegt Neu , Gibt an, dass die Nutzlast nicht verarbeitet wurde.
Eine geplante Aufgabe sucht die neuen Abzeichendatensätze in der Tabelle „Connector-Ereignisse“, transformiert sie und schreibt sie in die Tabelle „Mitarbeiteranwesenheitsdaten“ [sn_wsd_wc_Employee_Attendance_Data]. Das Feld Status wird dann auf festgelegt Verarbeitet .
Die Zuordnung der Daten zwischen den Nutzlastdaten im Datensatz „Connector-Ereignisse“ und dem Datensatz „Mitarbeiteranwesenheitsdaten“ wird in einem Erweiterungspunkt definiert. Dieser Erweiterungspunkt wird im Feld „Erweiterungspunktdefinition“ in der Tabelle „zugehörige Connector-Konfiguration“ [sn_wsd_wc_Connector_config] identifiziert. Für diesen Endpunkt ist dies der BadgingDataHandler-Erweiterungspunkt.
Verarbeitet status werden nach zwei Tagen ab dem Erstellungsdatum gelöscht. Datensätze in Fehler status werden nach sieben Tagen ab dem Datum der Erstellung gelöscht. Datensätze in Neu status wurde nie gelöscht.URL-Format
Versionierte URL: /api/sn_wsd_wc/{api_Version}/Workplace_Connector_Webhook/event
Standard-URL: /api/sn_wsd_wc/Workplace_Connector_Webhook/event
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| api_version | Optional. Version des Endpunkts, auf den zugegriffen werden soll. Beispiel: v1 Oder v2 . Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| ni.nolog.id | Erforderlich. SYS_ID des Anbieterkonfigurationsdatensatzes, der der Hardware zugeordnet ist, die die Ereignisinformationen generiert hat. Datentyp: Zeichenfolge Tabelle: Anbieterkonfiguration [sn_wsd_wc_Provider_config] |
| Token_Name | Name des Sicherheitstoken, z. B. ein Anwendername oder ein anderer Wert, der das Sicherheitstoken identifiziert. Wird zum Authentifizieren der Anforderung verwendet. Datentyp: Zeichenfolge Tabelle: Anbieterkonfiguration [sn_wsd_wc_Provider_config] |
| Token_Wert | Wert, der dem Sicherheitstoken zugeordnet ist, z. B. ein Passwort. Wird zum Authentifizieren der Anforderung verwendet. Datentyp: Zeichenfolge Tabelle: Anbieterkonfiguration [sn_wsd_wc_Provider_config] |
| Name | Beschreibung |
|---|---|
| <payload> | Name-Wert-Paare der Hardware-/sensorbasierten Ereignisdaten. Die Namen müssen den Namen entsprechen, die im BadgingDataHandler-Erweiterungspunkt identifiziert wurden. Zum Beispiel: Sie können Daten mehrerer Ereignisse innerhalb eines einzelnen Endpunkts übergeben. Übergeben Sie die Daten jedes Ereignisses in einem separaten Objekt. Die Daten jedes Ereignisses werden in einem separaten Datensatz mit Mitarbeiteranwesenheitsdaten gespeichert. Hinweis: Stellen Sie sicher, dass der angegebene Zeitstempel der ISO 8601-Formatierung entspricht, um Probleme mit der Datumsanalyse zu vermeiden. Datentyp: JSON-Objekt |
Header
Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST-API-Header .
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Content-Type | Datenformat des Anforderungstexts. Unterstützt nur application/json. |
| Kopfzeile | Beschreibung |
|---|---|
| Keine |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter REST API-HTTP-Antwortcodes .
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 400 | Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt. |
| 401 | Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben. |
| 404 | Nicht gefunden. Das angeforderte Element wurde nicht gefunden. |
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler. |
Parameter des Antwort-Haupttexts
| Name | Beschreibung |
|---|---|
| Fehler | Beschreibung eines Fehlers, der während der Verarbeitung der Daten aufgetreten ist. Datentyp: Objekt |
| error.detail | Informationen, die Details zum Fehler enthalten. Datentyp: Zeichenfolge |
| Fehler.Nachricht | Fehlermeldung. Datentyp: Zeichenfolge |
| status | Status der Endpunktverarbeitung. Mögliche Werte:
Datentyp: Zeichenfolge |
cURL-Anforderung
Das folgende Codebeispiel zeigt, wie dieser Endpunkt aufgerufen wird, um der Tabelle „Connector-Ereignisse“ mehrere Kartenleserereignisse hinzuzufügen. Vor der Verarbeitung der Anforderung wird die Anforderung authentifiziert.
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\"
}"Antwort:
// 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"
}