Seitenhistorie

Authentication and Authorization

Siehe Artikel Informationen zur Authentifizierung.

Anfrage-Protokolle

Anfrage:

• Endpunkt: cloud-service-logging/accounts/$account/logs/paginated
• Methode: GET
• URL-Parameter: lang EN/DE
  • Grenze: 1..200
  • Kategorien OTHER, DEVICE
  • Markierungszeichenfolge

Antwort:

{
    "logs": [{
        "id": uuid,
        "messageId": string, // format 5 digit
        "created": timestamp, // yyyy-mm-ddThh:mm:ss.SSSZ
        "properties":{
            "auditEntityId": uuid,
            "auditNewValue": string,
            "auditOldValue": string,
            "auditSourceIp": string, // IPv4 address
            "auditEntityName": string,
            "auditEntityType": string,
            "auditSourceAgent": string,
            "auditOldValueChange": string,
            "auditNewValueChange": string
        },
        "references":[
            {
                "id": uuid,
                "type": string // account, addin, device, network, principal, site, page
            },
            {
                "id": uuid,
                "type": string,
                "name": string
            }],
        "data":[],
        "accountId": uuid,
        "originatorId": uuid,
        "serviceId": uuid,
        "serviceName": string,
        "logLevel": string, // INFO, WARNING, ERROR
        "message": string
        "isAuditLog": boolean
        },
        ...
    ],
    "next": string, // this parameter is optional
    "previous": string // this parameter is optional
}

Die Markierung ist die url-kodierte Version des nächsten Feldes.

Es ist möglich, Protokolle anzufordern, die neuer sind als ein bestimmter Zeitstempel:

curl -X GET -H  "accept: application/json" -H  "Authorization: Bearer $token" https://cloud.lancom.de/cloud-service-logging/accounts/$account/logs/paginated?lang=EN&categories=OTHER&marker=%7B%22type%22:%22PREVIOUS_PAGE%22,%22logCreatedAt%22:1613145056300000%7D

Referenzauflösung

Das Log-Objekt enthält verschiedene Arten von Referenzen, das Referenzformat ist:

{
    "id": uuid
    "type": string
    "name": string
}

id und type sind obligatorisch und immer im Referenzobjekt vorhanden. Der Name ist optional und nur für die Referenz vom Typ principal vorhanden.

Account

Diese Referenz steht für das Projekt, die Organisation oder die Verteilung.

Anfrage:

• Endpunkt: /cloud-service-auth/accounts
• Methode: GET
• URL-Parameter:
  • id: Liste von Konto-UUIDs

Antwort:

[
  {
    "name": string,
    "id": uuid,
    "parent": uuid,
    ...
    "identifier": string,
    "created": timestamp, // yyyy-mm-ddThh:mm:ss.SSS+ZZ:ZZ
    ...
  }
]

Addin

Anfrage:

Endpunkt: /cloud-service-config/configapplication/accounts/$account/applications
Methode: GET

Antwort:

[
  {
    "name": string,
    "enabled": boolean,
    "type": string,
    ...
    "id": uuid
  },
  ...
]

Device

Anfrage:

• Endpunkt: cloud-service-devices/accounts/$account/devices
• Methode: GET
• URL-Parameter:
  • id: device uuid

Antwort:

[
  {
    "id": uuid,
    "status": {
      "name": string,
      "serial": string,
      ...
    },
    ...
  }
]

Network

Anfrage:

• Endpunkt: /confignetwork/accounts/$account/networks
• Methode: GET

Antwort:

[
  {
    "id": uuid,
    "name": string,
    ...
]

Principal

Anfrage:

• Endpunkt: /cloud-service-auth/accounts/$account/members
• Methode: GET
• URL-Parameter:
  • id: principal uuid

Antwort:

[
  {
    "id": uuid,
    "icon": string,
    "name": string,
    "email": string,
    ...
  }
]

Site

Anfrage:

• Endpunkt: /cloud-service-devices/accounts/$account/sites
• Methode: GET
• URL-Parameter:
  • id: site uuid

Antwort:

[
  {
    "name": string,
    "comment": string,
    ...
    "id": uuid,
    ...
  }
]

Page

Der Seitenverweis hat eine statische Auflösung:

Vorlage und Referenz

Die Protokollmeldungen sind unveränderlich, eine Änderung in der Datenbank ist nicht möglich. Wenn sich die Darstellung der Meldungen ändert, verwenden wir eine Vorlage, um die aktualisierte Benennung von Geräten, Netzwerken, Auftraggebern usw. übernehmen zu können.

Hier wird sämtlicher Inhalt des Dokuments in Deutsch eingefügt!einige Beispiele für Vorlagen:

"User {ref:f16783c3-cb0c-3727-95c1-0752f938f7a7} has logged in for this account"
"The device {ref:ce4e47f6-c374-44dd-ba58-750a06e9c363} has established its cloud connectivity."

Die Zeichenfolge {ref:uuid} wird durch den Namen der Referenz ersetzt. Bei einigen Referenzen ist der Name in die Protokollnachrichten eingebettet (z. B. metric, principal), bei anderen Referenzen werden nur der Typ und die uuid angegeben. Die Namensauflösung erfordert dann einen zusätzlichen Aufruf der entsprechenden, oben aufgeführten API.

Authentication and Authorization

See article Informations on authentication.

Request logs

Request:

• Endpoint: cloud-service-logging/accounts/$account/logs/paginated
• Method: GET
• URL Params:
  • lang EN/DE
  • limit 1..200
  • categories OTHER, DEVICE
  • marker string

Response:

{
    "logs": [{
        "id": uuid,
        "messageId": string, // format 5 digit
        "created": timestamp, // yyyy-mm-ddThh:mm:ss.SSSZ
        "properties":{
            "auditEntityId": uuid,
            "auditNewValue": string,
            "auditOldValue": string,
            "auditSourceIp": string, // IPv4 address
            "auditEntityName": string,
            "auditEntityType": string, 
            "auditSourceAgent": string,
            "auditOldValueChange": string,
            "auditNewValueChange": string
        },
        "references":[
            {
                "id": uuid,
                "type": string // account, addin, device, network, principal, site, page 
            },
            {
                "id": uuid,
                "type": string, 
                "name": string
            }],
        "data":[],
        "accountId": uuid, 
        "originatorId": uuid,
        "serviceId": uuid,
        "serviceName": string,
        "logLevel": string, // INFO, WARNING, ERROR
        "message": string
        "isAuditLog": boolean
        },
        ...
    ],
    "next": string, // this parameter is optional
    "previous": string // this parameter is optional
}

Markers

The log messages API returns up to two markers: next and previous. These markers have the following format:

{
        "type": string // NEXT_PAGE, PREVIOUS_PAGE
        "logCreatedAt": timestamp // seconds from 1/1/1970
        "logPersistedAt": timestamp // seconds from 1/1/1970
    }

The marker is the url-encoded version of next field.

It is possible to request the logs newer than a specific timestamp:

curl -X GET -H  "accept: application/json" -H  "Authorization: Bearer $token" https://cloud.lancom.de/cloud-service-logging/accounts/$account/logs/paginated?lang=EN&categories=OTHER&marker=%7B%22type%22:%22PREVIOUS_PAGE%22,%22logCreatedAt%22:1613145056300000%7D

Reference Resolution

The log object contains different types of references, the reference format is:

{
    "id": uuid
    "type": string
    "name": string
}

The id and type are mandatory and always present in the reference object. The name is optional, and present only for the reference of type principal.

Account

This reference represents the project, the organization or the distribution.

Request:

• Endpoint: /cloud-service-auth/accounts
• Method: GET
• URL params:
  • id: list of account uuids

Response:

[
  {
    "name": string,
    "id": uuid,
    "parent": uuid,
    ...
    "identifier": string,
    "created": timestamp, // yyyy-mm-ddThh:mm:ss.SSS+ZZ:ZZ
    ...
  }
]

Addin

Request:

• Endpoint: /cloud-service-config/configapplication/accounts/$account/applications
• Method: GET

Response:

[
  {
    "name": string,
    "enabled": boolean,
    "type": string,
    ...
    "id": uuid
  },
  ...
]

Device

Request:

• Endpoint: cloud-service-devices/accounts/$account/devices
• Method: GET
• URL params:
  • id: device uuid

Response:

[
  {
    "id": uuid,
    "status": {
      "name": string,
      "serial": string,
      ...
    },
    ...
  }
]

Network

Request:

• Endpoint: /confignetwork/accounts/$account/networks
• Method: GET

Response:

[
  {
    "id": uuid,
    "name": string,
    ...
]

Principal

Request:

• Endpoint: /cloud-service-auth/accounts/$account/members
• Method: GET
• URL params:
  • id: principal uuid

Response:

[
  {
    "id": uuid,
    "icon": string,
    "name": string,
    "email": string,
    ...
  }
]

Site

Request:

• Endpoint: /cloud-service-devices/accounts/$account/sites
• Method: GET
• URL params:
  • id: site uuid

Response:

[
  {
    "name": string,
    "comment": string,
    ...
    "id": uuid,
    ...
  }
]

Page

The page reference has a static resolution:

Template and Reference

The log messages are immutable, it is not possible to change in the database. The rendering of the messages changes, we use a template to then be able to have the updated naming of devices, networks, principals...

Here some template examples:

"User {ref:f16783c3-cb0c-3727-95c1-0752f938f7a7} has logged in for this account"
"The device {ref:ce4e47f6-c374-44dd-ba58-750a06e9c363} has established its cloud connectivity."

The string {ref:uuid} is replaced with name of the reference. Some references have the name embedded in the log messages (e.g. metric, principal), other references only specify the type and the uuid. The name resolution then requires an additional call to the corresponding API, listed above.