REST API de Monitoramento (versão 1)
Abaixo é apresentada a API REST disponível relacionada com usuários monitorados.
Caso qualquer requisição a API apresentada nesta página seja considerada como não monitorada conforme regras de inclusões e exclusões, será respondido com código de erro 403.
Caso o sistema de privacidade dos dados do usuário esteja ligado, qualquer requisição a API
que tente criar um usuário com os campos abaixos preenchidos ou editar tais campos em um usuários existente que não consentiu com o termo de privacidade,
será respondido com código de erro 409:
friendlyId, firstName, middleName, lastName, email e
atributos customizados com a opção Identifica usuário
habilitada.
Para melhor entender quando se utiliza cada operação apresentada nesta página, iniciaremos apresentando cenários de uso e em seguida as operações são apresentadas em detalhes.
Cenário de uso: monitoramento por sistema externo sem uso de identificador amigável
Neste cenário um sistema externo utiliza o monitoramento do LumisXP, sem utilização do campo de identificador amigável do usuário. Neste caso o sistema externo usará o identificador de rastreamento do usuário, possivelmente armazenando-o associado ao usuário do sistema, como forma de poder referenciar o mesmo usuário quando necessário.
Um uso básico neste cenário seria:
- Um usuário inicia sua interação com o sistema externo. Se o sistema ainda não possui um identificador de rastreamento para este usuário, ele irá gerá-lo executando POST .../users. A chamada para esta operação irá retornar o identificador de rastreamento do usuário que o sistema externo deverá armazenar de forma que possa reutilizá-lo sempre que quiser referenciar este mesmo usuário.
-
Quando o sistema externo quiser armazenar informação sobre alguma ação feita pelo usuário, poderá utilizar a operação
POST .../events/{id}/data,
repassando como valor da propriedade
lum_user.trackId
o identificador de rastreamento do usuário. Isto fará com que campos que o evento possua correspondente a dados do usuários (lum_user.*
) sejam preechidos com os dados correspondentes. - Quando o sistema externo quiser atualizar alguma informação sobre este usuário, poderá utilizar a operação PATCH .../users/{trackId}[*].
Cenário de uso: monitoramento por sistema externo com uso de identificador amigável
Neste cenário um sistema externo utiliza o monitoramento do LumisXP, utiliza sua própria forma de identificar um usuário como identificador amigável no usuário do LumisXP.
Por exemplo, suponhamos que o sistema possui seus usuários cadastrados em um Active Directory, e utiliza como forma de identificar o usuário o seu login. Estes usuários podem ser importados para também existirem no LumisXP ou não. Caso sejam importados, neste exemplo a configuração de identificador amigável de usuários deve ser configurada para que corresponda ao login (assumindo que está no mesmo formato do login do sistema externo), para ser consistente com a forma que o sistema externo irá gerar esses identificadores.
Neste caso o sistema externo não precisa persistir de forma permanente o identificador de rastreamento do usuário, pois poderá recuperá-lo a partir do identificador amigável que foi definido pelo próprio sistema. Ele precisará manter o identificador de rastreamento do usuário em caso em que ainda não tem conhecimento de qual seu usuário está efetuando acesso (por exemplo, um website que permite acesso sem autenticação) e manter temporariamente no caso de usuário conhecido para evitar ter que chamar sempre a operação para recuperar o identificador de rastreamento a partir do identificador amigável (em ambos os casos, em uma aplicação web, é comum para isto armazenar o identificador de rastreamento[*] em web storage, cookie ou sessão).
Um uso básico neste cenário seria:
- Um usuário inicia sua interação com o sistema externo. Se o sistema ainda não possui um identificador de rastreamento para este usuário, ele irá gerá-lo executando o POST .../users, opcionalmente incluindo informações conhecidas sobre o usuário para serem armazenadas no monitoramento do LumisXP. Caso já se saiba o identificador amigável deste usuário (por exemplo, já foi autenticado), o identificador amigável deve ser passado nesta chamada para que seja utilizado o usuário correspondente.
-
Quando o sistema externo quiser armazenar informação sobre alguma ação feita pelo usuário, poderá utilizar a operação
POST .../events/{id}/data,
repassando como valor da propriedade
lum_user.trackId
o identificador de rastreamento do usuário. Isto fará com que campos que o evento possua correspondente a dados do usuários (lum_user.*
) sejam preechidos com os dados correspondentes. - Quando o sistema externo quiser atualizar alguma informação sobre este usuário, poderá utilizar a operação PATCH .../users/{trackId}[*].
- Quando o usuário for reconhecido pelo sistema externo de forma que ele passe a saber o identificador amigável antes não conhecido (por exemplo, ao efetuar login), deve ser utilizada a operação POST .../users/{trackId}/identify[*], que fará atualização dos usuários correspondentes se necessário e retornará o identificador de rastreamento do usuário que deve ser usado para referenciar o usuário com o identificador amigável especificado.
POST /lumis/api/rest/lumis/monitor/v1/users
Adiciona um usuário ou atualiza um usuário com um friendlyId
especificado[*].
Cabeçalhos de Requisição
Esta operação requer cabeçalhos na requisição compatíveis com:
Cabeçalho | Valor |
---|---|
Content-Type | application/json |
Accept | application/json |
Corpo da Requisição
O corpo da requisição deve ser um objeto JSON com as propriedades listadas abaixo:
Propriedade | Requerido | Descrição | Tipo | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
friendlyId | Não | O identificador único amigável que será atribuído a este usuário. Se já existir um usuário com este identificador amigável, tal usuário será atualizado com as informações fornecidas por esta operação. Caso contrário um novo usuário será criado. | string, até 255 caracteres. | ||||||||||
firstName | Não | Primeiro nome. | string, até 100 caracteres. | ||||||||||
middleName | Não | Nome do meio. | string, até 100 caracteres. | ||||||||||
lastName | Não | Último nome. | string, até 100 caracteres. | ||||||||||
Não | Endereço de e-mail. | string, até 255 caracteres. | |||||||||||
customAttributes | Não | Especifica valores a serem aplicados a atributos customizados. Para poder atribuir um valor a um atributo
customizado, ele precisa ter sido previamente cadastrado em
atributos de usuário nas configurações do portal.
O valor desta propriedade deve ser um objeto JSON que contém propriedades cujo nome é o identificador do
atributo de usuário correspondente, e cujo valor é um valor único ou uma lista de valores a ser aplicado àquele atributo. O tipo do valor de cada elemento
declarado no JSON deve corresponder ao tipo cadastrado para aquele atributo conforme a tabela abaixo:
|
object |
Resposta de Sucesso
Quando a operação é bem sucedida, a resposta conterá um objeto JSON informação sobre a ação executada e o identificador do usuário criado ou atualizado.
Propriedade | Descrição | Tipo | Sempre Presente |
---|---|---|---|
created | Terá valor true se um novo usuário foi criado, ou false se um existente foi atualizado. |
boolean | Sim |
lum_user.trackId | O identificador de rastreamento do usuário criado ou atualizado. | string | Sim |
Resposta de Erro
Esta operação responde como erro o objeto JSON padrão de erro.
Exemplo de Requisição
POST /lumis/api/rest/lumis/monitor/v1/users HTTP/1.1
Accept: application/json
Content-Type: application/json
(... outros cabeçalhos ...)
{
"friendlyId": "11111111111",
"firstName": "John",
"middleName": "Doe",
"lastName": "Smith",
"email": "jds@example.com",
"customAttributes":
{
"active": false,
"classes": 5,
"company": "Acme",
"memberSince": "1980-12-02T05:23:26-03:00",
"phone": ["(00)1234-5678","(11)98765-4321"]
}
}
Exemplo de Resposta de Sucesso
{
"created": false,
"lum_user":
{
"trackId": "d4JdixacSOUHzGuStMaUaOAjE8VF42WI"
}
}
PATCH /lumis/api/rest/lumis/monitor/v1/users/{trackId}
Atualiza dados de um usuário[*].
Cabeçalhos de Requisição
Esta operação requer cabeçalhos na requisição compatíveis com:
Cabeçalho | Valor |
---|---|
Content-Type | application/merge-patch+json |
Accept | application/json |
Parâmetros na URI
Parâmetro | Descrição |
---|---|
{trackId} | Identificador de rastreamento do usuário que será atualizado. |
Corpo da Requisição
O corpo da requisição deve ser um objeto JSON contendo as propriedades do usuário a serem alteradas. As
propriedades aceitas neste objeto são as mesmas descritas no método POST acima, exceto
friendlyId
, que não é permitido ser declarado nesta operação.
Resposta de Sucesso
A resposta desta operação em caso de sucesso será o corpo vazio e código de resposta 204.
Resposta de Erro
Esta operação responde como erro o objeto JSON padrão de erro.
Exemplo de Requisição
Neste exemplo será atualizado o valor de email
e será apagado o atributo
customizado company
, caso exista.
PATCH /lumis/api/rest/lumis/monitor/v1/users/d4JdixacSOUHzGuStMaUaOAjE8VF42WI HTTP/1.1
Content-Type: application/merge-patch+json
Accept: application/json
(... outros cabeçalhos ...)
{
"email": "my_new_email@example.com",
"customAttributes":
{
"company": null
}
}
POST /lumis/api/rest/lumis/monitor/v1/users/{trackId}/identify
Identifica um usuário com um identificador amigável[*], retornando o identificador de rastreamento do usuário resultante com tal identificador amigável.
Se o usuário com o identificador de rastreamento dado não possui identificador amigável e não existe usuário com identificador amigável igual ao valor especificado, este usuário passará a ter o identificador amigável especificado e seu identificador de rastreamento será retornado.
Se o usuário com o identificador de rastreamento dado não possui identificador amigável mas já existe usuário com identificador amigável igual ao valor especificado, ambos usuários serão mesclados em um único usuário e o seu identificador de rastreamento será retornado.
Se o usuário com o identificador de rastreamento dado já possui identificador amigável igual ao valor especificado, nenhuma alteração será feita e o seu identificador de rastreamento será retornado.
Se o usuário com o identificador de rastreamento dado já possui identificador amigável mas diferente do valor especificado, e se não existir um usuário com este identificador amigável, um novo usuário será criado com o identificador amigável e o seu identificador de rastreamento será retornado.
Se o usuário com o identificador de rastreamento dado já possui identificador amigável diferente do valor especificado, e se existir um usuário com este identificador amigável, será retornado o identificador de rastreamento deste usuário já existente.
Cabeçalhos de Requisição
Esta operação requer cabeçalhos na requisição compatíveis com:
Cabeçalho | Valor |
---|---|
Content-Type | application/json |
Accept | application/json |
Parâmetros na URI
Parâmetro | Descrição |
---|---|
{trackId} | Identificador de rastreamento do usuário. |
Corpo da Requisição
O corpo da requisição deve ser um objeto JSON com as propriedades listadas abaixo:
Propriedade | Requerido | Descrição | Tipo |
---|---|---|---|
friendlyId | Sim | Identificador amigável | string, até 255 caracteres. |
Resposta de Sucesso
Quando a operação é bem sucedida, a resposta conterá um objeto JSON com o identificador de rastreamento do usuário que possui o identificador amigável especificado.
Propriedade | Descrição | Tipo | Sempre Presente |
---|---|---|---|
lum_user.trackId | O identificador de rastreamento do usuário. | string | Sim |
Resposta de Erro
Esta operação responde como erro o objeto JSON padrão de erro.
Exemplo de Requisição
POST /lumis/api/rest/lumis/monitor/v1/users/d4JdixacSOUHzGuStMaUaOAjE8VF42WI/identify HTTP/1.1
Content-Type: application/json
Accept: application/json
(... outros cabeçalhos ...)
{
"friendlyId": "111111111111"
}
Exemplo de Resposta de Sucesso
{
"lum_user":
{
"trackId": "d4JdixacSOUHzGuStMaUaOAjE8VF42WI"
}
}
Observação sobre a privacidade do usuário
Para usuários que não possuam login, para ser possível armazenar primeiro nome (firstName
),
nome do meio (middleName
), último nome (lastName
), e-mail (email
),
identificador amigável (friendlyId
) ou algum atributo customizado
que tenha a flag Identifica usuário ligada, o usuário atualmente rastreado deve, necessariamente,
ter consentido com ao menos um termo de privacidade
no ambiente.