Data Streams

Dokumentation

Data Streamer Funktionalität

Allgemeine Informationen

1NCE bietet einen Service namens „Data Streams“ an. Der Datenstromdienst ermöglicht es, Ereignis- und Nutzungsdaten für alle SIM-Karten in Echtzeit abzurufen, indem Daten direkt auf den Kundenserver oder einen bereits integrierten Cloud-Service wie AWS Kinesis, DataDog oder Keen.io übertragen werden. Insgesamt können bis zu zehn verschiedene Data Streams pro Kundenkonto konfiguriert werden.

 

Konfiguration der Datenstrom Funktion

Die Einrichtung eines Datenstroms auf der Registerkarte Konfiguration im 1NCE Kundenportal erfordert, dass der Kunde den Stream-Typ auswählt, um anzugeben, ob nur Ereignis- oder Nutzungsdaten gewünscht sind oder ob beide gemeinsam gesendet werden sollen.

Der Kunde kann die Übertragung von historischen Daten wählen. Bei Auswahl historischer Daten sendet die 1NCE-Plattform alle Kundendaten, die bis zu sieben Tage alt sind, wobei zu bedenken ist, dass es jedoch deutlich länger dauert, bis die Übertragung der Live-Daten aufgeholt wird.

Ein aktivierter und konfigurierter Stream wird sofort aktiv und die Performance der Karten kann sofort überwacht werden. Der aktuelle Remote-Status wird im Kundenportal als HTTP-Status angezeigt, der vom Remote-Standort kodiert wird. Wenn ein 200 (OK) angezeigt wird, arbeitet der Datenstrom normal. Falls die ausgewählte Applikation nicht erreichbar ist oder die Konfiguration ungültig ist, wird ein 500er-Fehler angezeigt.

Kunden können die Übertragung jederzeit anhalten und fortsetzen, indem sie die Aktionstasten neben den Stream Details verwenden.

Für die Einrichtung der Datenströme für eine RestAPI oder RestAPI im Bulk-Modus, ist die Angabe eines API-Callbacks erforderlich. Der 1NCE Datenstrom fungiert als HTTP-Client und benötigt einen HTTP-Server, um jede Übertragung zu verarbeiten. Jede gesendete Nachricht beinhaltet ein Array von einem oder mehreren Objekten.

 

Event Daten

Um die Ereignisdaten besser zu verstehen, bieten die folgenden Schritte einen detaillierten Überblick über die Eigenschaften der Ereignisdaten und einige typische Beispiele für ein besseres Verständnis auf praktischer Ebene.

 

Eigenschaften der Event Daten

Ereignisdaten werden von dem Endgerät mit der 1NCE SIM-Karte immer dann erzeugt, wenn Änderungen auftreten, wie z.B. ein Standortwechsel, ein Fehler oder eine Störung. Dies gibt dem Kunden einen Hinweis auf unvorhergesehene Ereignisse oder die Notwendigkeit, etwas zu unternehmen. Zur Übersicht werden alle möglichen Ereignistypen und -eigenschaften wie folgt aufgelistet.

1. Übersicht der Ereignisdaten
Id Beschreibung
0 Generic
1 Update location
2 Update GPRS location
3 Create PDP Context
4 Update PDP Context
5 Delete PDP Context
6 User authentication failed
7 Application authentication failed
8 SIM activation
9 SIM suspension
10 SIM deletion
11 Endpoint blocked
12 Organization blocked
13 Support Access
14 Multi-factor Authentication
15 Purge Location
16 Purge GPRS Location
17 Self-Signup
18 Threshold reached
19 Quota used up
2. Allgemeine Event Daten

Die folgenden Eigenschaften sind in allen gesendeten Ereignissen enthalten:

Eigenschaft_______ Format_______ Beschreibung
id Numerisch Eindeutige Kennung dieses Ereignisses. Wenn mehrere Ereignisse mit gleicher ID empfangen werden (z.B. aufgrund von Übertragungsfehlern), sollten diese vom Empfänger als Duplikate behandelt werden.
timestamp Zeitstempel Datum/Uhrzeit des Ereignisses
event_type Verschachteltes
Objekt
Typ des Ereignisses, siehe unten für Details
event_severity Verschachteltes
Objekt
Schweregrad des Ereignisses, siehe unten für Details
event_source Verschachteltes
Objekt
Quelle des Ereignisses, siehe unten für Details
organisation Verschachteltes
Objekt
Organisation verbunden mit dem Ereignis, siehe unten für Details
alert Boolesch Das Ereignis soll den Benutzer alarmieren
description Zeichenfolge Lesbare Beschreibung des Ereignisses
3. Optionale Eigenschaften

Ereignistypen, die sich auf bestimmte SIM-Karten oder Benutzer beziehen, beinhalten die folgenden zusätzlichen Eigenschaften:

Eigenschaft_______ Format_______ Beschreibung
imsi Verschachteltes
Objekt
Details einer IMSI, siehe unten für Details
sim Verschachteltes
Objekt
Details der SIM-Karte, siehe unten für Details (im Falle einer Multi-IMSI-Konfiguration können mehrere verschiedene IMSI-Daten für dieselbe SIM-Karte gemeldet werden)
endpoint Verschachteltes
Objekt
Details zum Endpunkt, siehe unten für Details
4. Eigenschaften der Detailobjekte
Eigenschaft_______ Format_______ Beschreibung
id Numerisch Eindeutige Kennung des aktuell verwendeten Mobilfunkbetreibers
name Zeichenfolge Name des Mobilfunkanbieters
country Verschachteltes
Objekt
Land des Mobilfunkanbieters
country.id Numerisch Eindeutige Kennung des Landes
country.name Zeichenfolge Name des Landes
country.country_code Zeichenfolge Ländercode
country.mcc Zeichenfolge Mobile Country Code (MCC)
country.iso_code Zeichenfolge ISO Code
pdp_context Verschachteltes
Objekt
PDP Context Details
volume Verschachteltes
Objekt
Verbrauchtes Volumen im PDP Context
volume.rx Zahl mit bis zu 6 Nachkommastellen Downstream Volumen in MB
volume.tx Zahl mit bis zu 6 Nachkommastellen Upstream Volumen in MB
volume.total Zahl mit bis zu 6 Nachkommastellen Gesamtvolumen
5. Eigenschaften des PDP Context
Eigenschaft Format_______ Beschreibung
pdp_context_id Zeichenfolge Eindeutige Kennung des PDP context
tunnel_created Zeitstempel Datum/Uhrzeit zu PDP context created
gtp_version Zeichenfolge GTP Version, 1 oder 2
ggsn_control_plane_ip_address Zeichenfolge IP Adresse des GGSN/PGW Control Plane
ggsn_data_plane_ip_address Zeichenfolge IP Adresse des GGSN/PGW Data Plane
sgsn_control_plane_ip_address Zeichenfolge IP Adresse des SGSN/SGW Control Plane
sgsn_data_plane_ip_address Zeichenfolge IP Adresse des SGSN/SGW Data Plane
region Zeichenfolge Region des Data Plane
breakout_ip Zeichenfolge IP Adresse für den Internet Breakout
apn Zeichenfolge Access Point Name (APN)
nsapi Ganzzahlig  Network Service Access Point Identifier (NSAPI)
ue_ip_address Zeichenfolge Endpoint zugeordnete IP Adresse
imeisv Zeichenfolge IMEISV
mcc Zeichenfolge Mobile Country Code (MCC)
mnc Zeichenfolge Mobile Network Code (MNC)
lac Ganzzahlig Location Area Code (LAC)
sac Ganzzahlig Service Area Code (SAC)
rac Ganzzahlig Routing Area Code (RAC)
ci Ganzzahlig Cell Identification (CI)
rat_type Ganzzahlig Radio Access Type (RAT) (1=3G, 2=2G, 3=WLAN, 4=GAN, 5=HSPA+, 6=4G, 8=NB-IoT)
6. Eigenschaften des IMSI Objekts
Eigenschaft_______ Format_______ Beschreibung
id Numerisch Eindeutige Kennung dieser IMSI
imsi Zeichenfolge International Mobile Subscriber Identity (IMSI)
import_date Zeitstempel Datum/Uhrzeit, zu der diese IMSI bereitgestellt wurde
7. Eigenschaften des Organisation Objekts
Eigenschaft Format Beschreibung
id Numerisch Eindeutige Kennung dieser Organisation
name Zeichenfolge Name der Organisation
8. Eigenschaften des User Objekts
Eigenschaft Format Beschreibung
id Numerisch Eindeutige Kennung dieses Users
username Zeichenfolge Benutzername, z.B. E-Mail-Adresse
name Zeichenfolge Realname des Benutzers
9. Eigenschaften des Endpoint Objekts
Eigenschaft Format Beschreibung
id Numerisch Eindeutige Kennung dieses Endpoints
name Zeichenfolge Der konfigurierte Name diese Endpoints
ip_address Zeichenfolge Diesem Endpoint zugeordnete IP-Adresse
tags Zeichenfolge Diesem Endpoint zugeordnete Tags
imei Zeichenfolge Internationale Identität mobiler Geräte (IMEI)
10. Eigenschaften des SIM Objekts
Eigenschaft_______ Format_______ Beschreibung
id Numerisch Eindeutige Kennung dieser SIM
iccid Zeichenfolge Integrated Circuit Card Identifier (ICCID) ohne elektronische Prüfziffer
msisdn Zeichenfolge MSISDN
production_date Zeitstempel Datum/Uhrzeit, zu der dieser SIM-Chip produziert wurde
11. Serverity Levels
Id Beschreibung
0 INFO
1 WARN
2 CRITICAL
12. Event Quelle
Id Beschreibung
0 Network
1 Policy Control
2 API

Event Daten Beispiel - JSON Format

1. "Update Location" Event Beispiel

{
„id“: 2013707XX,
„alert“: false,
„description“: „New location received from VLR for IMSI=’9014301234567891XXXX‘, now attached to VLR=’4917200130XX‘.“,
„timestamp“: „2017-10-26T07:28:00.000+0000“,
„event_type“: {
„id“: 1,
„description“: „Update location“
},
„event_source“: {
„id“: 0,
„description“: „Network“
},
„event_severity“: {
„id“: 0,
„description“: „Info“
},
„organisation“: {
„id“: 839921,
„name“: „Demo Company“
},
„endpoint“: {
„id“: 8638726,
„name“: „GPS Tracker“,
„ip_address“: „100.96.234.249“,
„tags“: null,
„imei“: „357762083301XXXX“
},
„imsi“: {
„id“: 205672,
„imsi“: „9014301234567891XXXX“,
„import_date“: „2016-12-27T10:09:23.000+0000“
},
„sim“: {
„id“: 274887,
„iccid“: „898830300123456XXXX“,
„production_date“: „2016-12-27T10:09:23.000+0000“
},
„detail“: {
„id“: 3,
„name“: „Telekom“,
„country“: {
„id“: 74,
„name“: „Germany“,
„country_code“: „49“,
„mcc“: „262“,
„iso_code“: „de“
},
„tapcode“: [{
„id“: 2,
„tapcode“: „DEUD2“
}],
„mnc“: [{
„id“: 3,
„mnc“: „02“
}]
}
}

2. "Delete PDP Context" Event Beispiel

{
„id“: 2013707XX,
„alert“: false,
„description“: „PDP Context deleted.“,
„timestamp“: „2017-10-26T07:27:59.000+0000“,
„event_type“: {
„id“: 5,
„description“: „Delete PDP Context“
},
„event_source“: {
„id“: 0,
„description“: „Network“
},
„event_severity“: {
„id“: 0,
„description“: „Info“
},
„organisation“: {
„id“: 839921,
„name“: „Demo Company“
},
„endpoint“: {
„id“: 8427408,
„name“: „GPS Tracker“,
„ip_address“: „10.194.50.XX“,
„tags“: null,
„imei“: „898830300123456XXXX“
},
„imsi“: {
„id“: 372566,
„imsi“: „9014301234567891XXXX“,
„import_date“: „2017-03-15T21:46:01.000+0000“
},
„sim“: {
„id“: 319318,
„iccid“: „898830300123456XXXX“,
„production_date“: „2017-03-15T21:46:01.000+0000“
},
„detail“: {
„id“: 48,
„name“: „SFR Cegetel“,
„volume“: {
„rx“: 0.012671,
„tx“: 0.01148,
„total“: 0.024151
},
„pdp_context“: {
„mcc“: „310“,
„tunnel_created“: „2017-12-11T05:49:29“,
„ggsn_control_plane_ip_address“: „185.57.216.XX“,
„pdp_context_id“: „162094787“,
„imeisv“: „898830300123456XXXX“,
„region“: „eu-west-1“,
„lac“: 40484,
„sac“: 61142,
„rat_type“: 1,
„gtp_version“: „1“,
„ue_ip_address“: „100.105.197.XX“,
„mnc“: „260“,
„sgsn_data_plane_ip_address“: „216.155.166.XXX“,
„ci“: null,
„apn“: null,
„tx_teid_control_plane“: 2667756875,
„rx_teid“: 2720724,
„rac“: null,
„imsi“: „9014301234567891XXXX“,
„sgsn_control_plane_ip_address“: „216.155.165.XXX“,
„nsapi“: 6,
„breakout_ip“: null,
„ggsn_data_plane_ip_address“: „185.57.216.XX“,
„tx_teid_data_plane“: 3095978
},
„country“: {
„id“: 68,
„name“: „France“,
„country_code“: „33“,
„mcc“: „208“,
„iso_code“: „fr“
}
}
}

3. "User Authentification Failed" Event Beispiel

{
„id“: 201388127,
„alert“: false,
„description“: „Failed authentication request from ‚user@company.com‘, Reason: Invalid password from IP 9.9.9.9“,
„timestamp“: „2017-10-26T07:42:00.000+0000“,
„event_type“: {
„id“: 6,
„description“: „User authentication failed“
},
„event_source“: {
„id“: 2,
„description“: „API“
},
„event_severity“: {
„id“: 1,
„description“: „Warn“
},
„organisation“: {
„id“: 839921,
„name“: „Demo Company“
},
„user“: {
„id“: 84993,
„username“: „user@company.com“,
„name“: „Scott Tiger“
}
}

Nutzungsdaten

Die von den 1NCE Datenströmen bereitgestellten Nutzungsdaten ermöglichen es dem Kunden, alle SIM-Karten genau zu überwachen und Probleme sowie Fehlverhalten von Geräten zu erkennen.

1. Eigenschaften von Nutzungsdaten

 

Eigenschaft Format Beschreibung
id Numerisch Eindeutige Kennung dieser Transaktion
cost Zahl mit bis zu 6 Nachkommastellen Kostenberechnung des gemeldeten Verbrauchsvolumen
currency.id Numerisch Eindeutige Kennung der Währung der angegebenen Kosten
currency.code ISO 4217 Währungscode
start_timestamp UTC Zeitstempel Startzeitpunkt der Verbrauchsmessung
end_timestamp UTC Zeitstempel Endzeitpunkt der Verbrauchsmessung
volume.rx Zahl mit bis zu 6 Nachkommastellen Downstream-Verbrauch (MB), der vom Endpunkt empfangen wird
volume.tx Zahl mit bis zu 6 Nachkommastellen Upstream-Verbrauch (MB), der vom Endpunkt empfangen wird
volume.total Zahl mit bis zu 6 Nachkommastellen Gesamtverbrauch
imsi 15-Stellige Nummernfolge Aktuell genutzte IMSI
endpoint.id Numerisch Eindeutige Kennung des Endpunkts
endpoint.name Zeichenfolge Nutzerdefinierter Name des Endpoints
endpoint.idp_address Numerisch Diesem Endpoint zugeordnete IP-Adresse
endpoint.tags Zeichenfolge Diesem Endpoint zugeordnete nutzerdefinierte Tags
endpoint.imei Numerisch Die IMEI der Hardware des Endpoints
sim.id Numerisch Eindeutige Kennung der SIM
sim.msisdn Numerisch MSISDN der SIM
sim.production_date Zeitstempel Das Produktionsdatum der SIM
sim.iccid 19-Stellige Nummernfolge ICCID der SIM
organisation.id Numerisch Eindeutige Kennung der Organisation
organisation.name Zeichenfolge Name der Organisation
operator.id Numerisch Eindeutige Kennung des Netzanbieters
operator.mnc Numerisch Mobile Network Code des verbundenen Netzwerk-Oprator
operator.name Zeichenfolge Name des Netzanbieters
operator.country.id Numerisch Eindeutige Kennung des Netzanbieter Landes
operator.country.mnc Numerisch Mobile Country Code des verbundenen Netzwerk-Operator
operator.country.name Zeichenfolge Name des Netzanbieter Landes
tariff.id Numerisch Eindeutige Kennung des angewandten Tarifs
tariff.name Zeichenfolge Name des Tarifs
tariff.ratezone.id Numerisch Eindeutige Kennung der angewandten Tarifzone
tariff.ratezone.name Zeichenfolge Name der Tarifzone
traffic_type.id Numerisch Eindeutige Kennung des Verbrauchstyp
traffic_type.name Zeichenfolge Name des Verbrauchstyp
2. Verbrauchsdaten Beispiel - JSON Format

{

„sim“:{

„production_date“:“2019-01-22 13:39:15″,

„msisdn“:“423111111111111″,

„id“:1337,

„iccid“:“1111111111111111111″

},

„traffic_type“:{

„id“:5,

„name“:“Data“

},

„cost“:0.0010142,

„volume“:{

„total“:0.005071,

„rx“:0.002418,

„tx“:0.002653

},

„imsi_id“:3506619,

„currency“:{

„symbol“:“ „,

„code“:“EUR“,

„id“:1

},

„start_timestamp“:“2019-11-06 15:50:58″,

„imsi“:“111111111111111″,

„operator“:{

„mnc“:“01″,

„id“:2,

„country“:{

„mcc“:“262″,

„id“:74,

„name“:“Germany“

},

„name“:“Telekom“

},

„endpoint“:{

„ip_address“:“10.10.10.1″,

„imei“:“1111111111111111″,

„id“:9635467,

„tags“:null,

„name“:“My Endpoint“

},

„organisation“:{

„id“:1337,

„name“:“My Org“

},

„id“:85579,

„tariff“:{

„id“:166,

„ratezone“:{

„id“:276,

„name“:“Zone I“

},

„name“:“Global Roaming I – 1kb“

},

„end_timestamp“:“2019-11-06 16:06:42″

}

Integration mit Cloud Services

AWS Kinesis

Die Integration mit AWS Kinesis erfordert einen AWS Access Key und einen Secret Key mit dem Recht, Daten entweder in alle Kinesis Datenströme oder in den gewünschten Datenstrom zu schreiben. Es wird empfohlen, einen eigenen IAM-Benutzer für die Verbindung anzulegen.

Da Kinesis ein regionaler Dienst ist, ist eine Angabe der AWS-Region erforderlich. Sie müssen den Namen des Streams angeben, in dem die Daten gespeichert werden sollen.

 

AWS S3

Die Integration mit AWS S3 erfordert einen AWS Access Key und einen Secret Key mit dem Recht, Daten entweder in alle S3 Buckets oder in den gewünschten Bucket zu schreiben. Es wird empfohlen, einen eigenen IAM-Benutzer für die Verbindung anzulegen. Da S3 ein globaler Dienst ist, ist eine Auswahl der AWS-Region nicht erforderlich. Sie müssen den Namen des S3 Bucket angeben, in dem die Daten gespeichert werden sollen.

Die Integration liefert CSV-Dateien an den S3 Bucket im folgenden Format:

  • Das Dateinamensformat events_YYYYYYMMDDD_HHHmmss.csv wird für Ereignisdaten verwendet.
  • Das Dateinamensformat cdr_YYYYYYMMDD_HHHmmss.csv wird für Nutzungsdaten verwendet.

 

Keen.IO

Die Integration mit keen.io bietet die Möglichkeit, umfangreiche Daten über Ihre SIM-Karten zu analysieren und einzubetten.

Die Integration erfordert einen keen.io-Account mit einem korrekten Project Key sowie den entsprechenden Write Key.

Kurz nach der Konfiguration werden erste Daten an keen.io. gesendet. Eingehende Daten können auf keen.io auf der Registerkarte „Streams“ ausgewertet werden. Abhängig vom Stream-Typ, den der Kunde konfiguriert hat, erscheinen ein oder zwei Streams mit folgenden Namen: 1NCEEventData & 1NCEUsageData.

 

Data Dog

Die Integration mit DataDog ermöglicht die Echtzeit-Leistungsüberwachung Ihrer SIMs. In Verbindung mit der 1NCE-Plattform wird es dem Kunden ermöglicht, Kennzahlen über die Nutzung Ihrer SIM-Karten zu sammeln und zu analysieren. Der Kunde kann Dashboards erstellen und Warnmeldungen zu bestimmten Situationen auslösen.

Die Integration erfordert ein DataDog-Konto mit einem aktiven Anwendungsschlüssel und einem API-Schlüssel.

Kurz nach der Konfiguration werden die ersten Daten an DataDog gesendet. Eingehende Daten können im DataDog Explorer überprüft werden und ebenfalls können im DataDog Explorer Dashboards erstellt werden.

Die Integration wird die folgenden Kennzahlen liefern:

  • Volumen
  • volume_tx
  • volume_rx
  • Endpunktkosten