Tempo aproximado para leitura: 00:07:10 min
Dúvida
Como consumir a API de Usuários.
Ambiente
Cross Segmentos - Backoffice RM - Integração - Todas as versões.
Solução
Este documento tem o objetivo exemplificar o uso da API de Usuários, a fim de utilizar todos os métodos implementados.
Serão apresentados 5 métodos, os quais foram implementados na API de Usuários, são eles:
1 - GET
2 - POST
3 - PUT
4 - PATCH
5 - DELETE
Roles (Manipulação de Perfis) A partir da versão 12.1.2306
Associação de Perfis (Roles)
Para adicionar e remover perfis á um usuário é necessário realizar as operações de Post/Delete nas rotas de perfis conforme abaixo
Víncular perfil ao usuário (Post)
Remover perfil do usuário (Delete)
1 - GET
1.1 - Get All (Recuperar todos os usuários)
1.1 GetAll
Configuração
Máscara de Url: http://{domínio}:{porta}/api/framework/v1/users
Exemplo de Configuração
Exemplo de Resultado
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
|
{ "hasNext": true,
"items": [
{
"id": "00001",
"meta": {
"resourceType": "User",
"created": "2014-07-07T15:32:15",
"lastModified": "2018-10-05T09:34:53"
},
"externalId": "00001",
"name": {
"formatted": "ITAMAR MENDES DA SILVEIRA"
},
"userName": "00001",
"emails": [
{
"value": "masterkeyweb@totvs.com.br",
"primary": true
}
],
(...) "active": false
},
]
} |
1.2 - GetOne (Recuperar usuário pelo Identificador)
Parâmetros
Expand: Parâmetro opcional, usado para determinar a(s) propriedade(s) expandables que devem ser retornadas expandidas.
Exemplo: ?expand=roles - Nesse exemplo, os perfis associados ao usuário serão retornados na resposta da requisição.
Valores padrão: Caso não sejam preenchidos todas as propriedades expandables serão retornadas sem serem expandidas.
1.2.1 GetOne
Configuração
Máscara de Url: http://{domínio}:{porta}/api/framework/v1/users/{id}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Id: 00001
Url Utilizada: http://localhost:8051/api/framework/v1/users/00001
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
{ "_expandables": [
"roles"
],
"id": "00001",
"meta": {
"resourceType": "User",
"created": "2014-07-07T15:32:15",
"lastModified": "2018-10-04T17:02:10"
},
"externalId": "82cca8a8-9198-4508-95c3-a0a40dc34fa2",
"name": {
"formatted": "ITAMAR",
"givenName": "ITAMAR"
},
"userName": "00001",
"emails": [
{
"value": "teste@totvs.com.br",
"primary": true
}
],
"active": true
} |
1.2.2 GetOne expandable
Neste exemplo vamos utilizar o expand=roles ao qual irá mostrar todos perfis vinculados a este usuário.
Configuração
Máscara de Url: http://{domínio}:{porta}/api/framework/v1/users/{id}?expand={campo}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Id: 00001
Url Utilizada: http://localhost:8051/api/framework/v1/users/00001?expand=roles
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
{ "_expandables": [
"roles"
],
"id": "00001",
"meta": {
"resourceType": "User",
"created": "2014-07-07T15:32:15",
"lastModified": "2018-10-04T17:02:10"
},
"externalId": "82cca8a8-9198-4508-95c3-a0a40dc34fa2",
"name": {
"formatted": "ITAMAR",
"givenName": "ITAMAR"
},
"userName": "00001",
"emails": [
{
"value": "stella.vilaca@totvs.com.br",
"primary": true
}
],
"active": true,
"roles": [
{
"company": "1",
"value": "DBA Custo"
},
{
"company": "1",
"value": "_eq_1EquipeNet_A"
} ]
} |
2 - POST
2 - Post (Inserir um usuário)
2. Post
Configuração
Máscara de Url: http://{domínio}:{porta}/api/framework/v1/users
Exemplo de Configuração
Exemplo de Entrada
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
{ "id": "testeapiusuario",
"meta": {
"resourceType": "User",
"created": "2018-09-21T16:49:57.336Z",
"lastModified": "2018-09-21T16:49:57.336Z"
},
"externalId": "0001e",
"name": {
"givenName": "TesteAPI",
"familyName": "Usuário"
},
"userName": "testeapiusuario",
"phoneNumbers": [
{
"value": "31974964158"
}
],
"emails": [
{
"value": "testeapi.usuario@totvs.com.br",
"type": "string",
"primary": true
}
],
"active": true,
"groups": [
{
"value": "01",
"display": "geral"
}
],
"title": "Mr",
"manager": [
{
"managerId": "01",
"displayName": "Geral"
}
]
} |
Exemplo de Resultado Positivo
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
{ "id": "testeapiusuario",
"meta": {
"resourceType": "User",
"created": "2018-09-21T16:49:57.336Z",
"lastModified": "2018-09-21T16:49:57.336Z"
},
"externalId": "0001e",
"name": {
"givenName": "TesteAPI",
"familyName": "Usuário"
},
"userName": "testeapiusuario",
"phoneNumbers": [
{
"value": "31974964158"
}
],
... |
Exemplo de Resultado Negativo
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
{ "Code": "RMSDbKeyException",
"Message": "Chave duplicada\r\n\r\nPossíveis causas:\r\n - inclusão de registro cujo valor da chave primária já existe\r\n - inclusão de registro cujo valor do índice único já existe",
"DetailMessage": " em RM.Lib.Data.DbServices.UpdateTable(DataTable table, UpdateMode mode, Boolean logOperation, String userName, Int32 batchSize) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Data\\RMSData.cs:linha 897\r\n em RM.Lib.Data.DbServices.UpdateTable(DataTable table, UpdateMode mode, String userName, Int32 batchSize) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Data\\RMSData.cs:linha 865\r\n em RM.Lib.Data.DbServices.QueryUpdate(DataSet dataSet, String tableName, String codUsuario) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Data\\RMSData.cs:linha 3429\r\n em RM.Lib.Data.DbServices.QueryUpdate(DataSet dataSet, String tableName) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Data\\RMSData.cs:linha 3423\r\n em RM.Glb.Seguranca.GlbUsuarioData.DoSaveRecord(DataSet dataSet, Int32& rowsAffected, Object ownerData) na C:\\RM\\Atual\\Release\\Glb-Globais\\RM.Glb.Seguranca.Data\\GlbUsuarioData.cs:linha 473\r\n em RM.Lib.Server.RMSDataServer.InternalSaveRecord(RMSContext context, DataSet& dataSet, Object ownerData, Boolean skipSecurity, Boolean skipSecurityCollumns) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\RMSDataServer.cs:linha 1477\r\n em RM.Lib.Server.RMSDataServer.SaveRecord(RMSContext context, DataSet& dataSet, Object ownerData) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\RMSDataServer.cs:linha 651\r\n em RM.Glb.Api.UserControllerServer.Save(String id, User record) na C:\\RM\\Atual\\Release\\Glb-Globais\\RM.Glb.Api\\UserController.Server.cs:linha 336\r\n em RM.Glb.Api.UserControllerServer.OnPost(User record) na C:\\RM\\Atual\\Release\\Glb-Globais\\RM.Glb.Api\\UserController.Server.cs:linha 269\r\n em RM.Lib.Server.RMSCrudServer`1.Post(T record) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\Api\\RMSCrudServer.cs:linha 80\r\n em RM.Lib.Api.RMSCrudController`1.OnPost(T record) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Api\\Controllers\\RMSCrudController.cs:linha 135\r\n em RM.Lib.Api.RMSCrudController`1.Post(T record) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Api\\Controllers\\RMSCrudController.cs:linha 125\r\n em lambda_method(Closure , Object , Object[] )\r\n em System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.<>c__DisplayClass10.<GetExecutor>b__9(Object instance, Object[] methodParameters)\r\n em System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ExecuteAsync(HttpControllerContext controllerContext, IDictionary`2 arguments, CancellationToken cancellationToken)\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.ApiControllerActionInvoker.<InvokeActionAsyncCore>d__0.MoveNext()\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.ActionFilterResult.<ExecuteAsync>d__2.MoveNext()\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Runtime.CompilerServices.TaskAwaiter`1.GetResult()\r\n em RM.Lib.Api.Server.ApiAuthenticationFilter.ResultWithChallenge.<ExecuteAsync>d__2.MoveNext() na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Api.Server\\Filters\\Api.AuthenticationFilter.cs:linha 193\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.AuthenticationFilterResult.<ExecuteAsync>d__0.MoveNext()\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.ExceptionFilterResult.<ExecuteAsync>d__0.MoveNext()",
"HelpUrl": null,
"Details": [
{
"Code": "Exception",
"Message": "Violation of PRIMARY KEY constraint 'PKGUSUARIO'. Cannot insert duplicate key in object 'dbo.GUSUARIO'. The duplicate key value is (testeapiusuario).\r\nThe statement has been terminated.",
"DetailMessage": null,
"HelpUrl": null,
"Details": [
{
"Code": "Exception",
"Message": "INSERT INTO [GUSUARIO] ([CODUSUARIO], [NOME], [STATUS], [DATAINICIO], [IGNORARAUTENTICACAOLDAP], [DATAEXPIRACAO], [CONFIRMABTNOK], [SENHA], [CONTROLE], [ULTIMACOLIGADA], [CODACESSO], [DTAEXPSENHA], [DIASEXPSENHA], [OBRIGAALTERARSENHA], [NUMLOGININVALIDO], [DATALOGININVALIDO], [EMAIL], [ACESSONET], [INTERNO1], [DATAULTIMOACESSO], [CODUSUARIOREDE], [DOMINIOREDE], [DATAULTIMOACESSOVALIDO], [USUARIOTWITTER], [SENHATWITTER], [USUARIOFACEBOOK], [SENHAFACEBOOK], [USUARIOLINKEDIN], [SENHALINKEDIN], [USERIDFLUIGIDENTITY], [NOMESOCIAL], [USERID], [RECCREATEDBY], [RECCREATEDON], [RECMODIFIEDBY], [RECMODIFIEDON]) VALUES ('testeapiusuario', null, 1, '08/10/2018 00:00:00', 'F', null, 1, 'jcmaAAAA', -17702, , 'Acesso01', null, , 'T', , null, 'testeapi.usuario@totvs.com.br', 'F', null, null, null, null, null, null, '\\FEz\\1B\\7F1\\18\\B7\\27', null, '\\FEz\\1B\\7F1\\18\\B7\\27', null, '\\FEz\\1B\\7F1\\18\\B7\\27', null, null, '9b69c210-8d20-45b6-afae-534ce10fd4b7', 'mestre', CONVERT ( DATETIME, CONVERT ( VARCHAR, GETDATE(), 120) ), 'mestre', CONVERT ( DATETIME, CONVERT ( VARCHAR, GETDATE(), 120) ))",
"DetailMessage": null,
"HelpUrl": null,
"Details": null
}
]
},
]
} |
3 - PUT
3 - Put (Atualizar um usuário)
3 - Put
Configuração
Máscara de Url: http://{domínio}:{porta}/api/framework/v1/users/{id}
Exemplo de Configuração
Domínio: localhost
Porta: 8099
Id: 00001
Url Utilizada: http://localhost:8051/api/framework/v1/users/testeapiusuario
Exemplo de Entrada
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
{ "id": "testeapiusuario",
"meta": {
"resourceType": "User",
"created": "2018-09-21T16:49:57.336Z",
"lastModified": "2018-09-21T16:49:57.336Z"
},
"externalId": "0001e",
"name": {
"givenName": "TesteAPI",
"familyName": "Usuário"
},
"userName": "testeapiusuario",
"phoneNumbers": [
{
"value": "31974964158"
}
],
"emails": [
{
"value": "testeapi2.usuario@totvs.com.br",
"type": "string",
"primary": true
}
],
"active": true,
"groups": [
{
"value": "01",
"display": "geral"
}
],
"title": "Mr",
"manager": [
{
"managerId": "01",
"displayName": "Geral"
}
]
} |
Exemplo de Resultado Positivo
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
|
{ "id": "testeapiusuario",
"meta": {
"resourceType": "User",
"created": "2018-09-21T16:49:57.336Z",
"lastModified": "2018-09-21T16:49:57.336Z"
},
"externalId": "0001e",
"name": {
"givenName": "TesteAPI",
"familyName": "Usuário"
},
"userName": "testeapiusuario",
"phoneNumbers": [
{
"value": "31974964158"
}
],
"emails": [
{
"value": "testeapi2.usuario@totvs.com.br",
"type": "string",
"primary": true
}
]
...} |
Exemplo de Resultado Negativo
Resultado (JSON)
|
1
2
3
4
5
6
7
|
{ "Code": "RMSApplicationException",
"Message": "Já existe um usuário com esse e-mail",
"DetailMessage": " em RM.Lib.RMSException.Throw(String message) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib\\Utils\\RMSException.cs:linha 131\r\n em RM.Glb.Seguranca.GlbUsuarioData.ValidateRow(DataRow row) na C:\\RM\\Atual\\Release\\Glb-Globais\\RM.Glb.Seguranca.Data\\GlbUsuarioData.cs:linha 759\r\n em RM.Lib.Server.RMSDataServer.ValidateTableRows(DataTable masterTable) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\RMSDataServer.cs:linha 2509\r\n em RM.Lib.Server.RMSDataServer.DoValidateRows(DataSet dataSet) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\RMSDataServer.cs:linha 2449\r\n em RM.Lib.Server.RMSDataServer.InternalSaveRecord(RMSContext context, DataSet& dataSet, Object ownerData, Boolean skipSecurity, Boolean skipSecurityCollumns) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\RMSDataServer.cs:linha 1413\r\n em RM.Lib.Server.RMSDataServer.SaveRecord(RMSContext context, DataSet& dataSet, Object ownerData) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\RMSDataServer.cs:linha 651\r\n em RM.Glb.Api.UserControllerServer.Save(String id, User record) na C:\\RM\\Atual\\Release\\Glb-Globais\\RM.Glb.Api\\UserController.Server.cs:linha 336\r\n em RM.Glb.Api.UserControllerServer.OnPut(String id, User record) na C:\\RM\\Atual\\Release\\Glb-Globais\\RM.Glb.Api\\UserController.Server.cs:linha 274\r\n em RM.Lib.Server.RMSCrudServer`1.Put(String id, T record) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Server\\Api\\RMSCrudServer.cs:linha 99\r\n em RM.Lib.Api.RMSCrudController`1.OnPut(String id, T record) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Api\\Controllers\\RMSCrudController.cs:linha 163\r\n em RM.Lib.Api.RMSCrudController`1.Put(String id, T record) na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Api\\Controllers\\RMSCrudController.cs:linha 152\r\n em lambda_method(Closure , Object , Object[] )\r\n em System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.<>c__DisplayClass10.<GetExecutor>b__9(Object instance, Object[] methodParameters)\r\n em System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ExecuteAsync(HttpControllerContext controllerContext, IDictionary`2 arguments, CancellationToken cancellationToken)\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.ApiControllerActionInvoker.<InvokeActionAsyncCore>d__0.MoveNext()\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.ActionFilterResult.<ExecuteAsync>d__2.MoveNext()\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Runtime.CompilerServices.TaskAwaiter`1.GetResult()\r\n em RM.Lib.Api.Server.ApiAuthenticationFilter.ResultWithChallenge.<ExecuteAsync>d__2.MoveNext() na C:\\RM\\Atual\\Release\\Lib\\RM.Lib.Api.Server\\Filters\\Api.AuthenticationFilter.cs:linha 193\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.AuthenticationFilterResult.<ExecuteAsync>d__0.MoveNext()\r\n--- Fim do rastreamento de pilha do local anterior onde a exceção foi gerada ---\r\n em System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n em System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n em System.Web.Http.Controllers.ExceptionFilterResult.<ExecuteAsync>d__0.MoveNext()",
"HelpUrl": null,
"Details": null
} |
4 - DELETE
4 - Delete (Deletar um usuário)
4 - Delete
Configuração
Máscara de Url: http://{domínio}:{porta}/api/framework/v1/users/{id}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Id: Teste_01
Url Utilizada: http://localhost:8051/api/framework/v1/users/Teste_01
Exemplo de Resultado Positivo Postman
Obs.: Em caso de sucesso, será retornado o respondeCode = 204 e a resposta em branco.
Exemplo de Resultado Negativo
Resultado (JSON)
|
1
2
3
4
5
6
7
|
{ "Code": "FE006",
"Message": "Violação de chave estrangeira\r\n\r\nPossíveis causas:\r\n - exclusão de registro que possui outros registros associados\r\n - inclusão de registro detalhe sem um registro mestre associado",
"DetailMessage": "The DELETE statement conflicted with the REFERENCE constraint \"FKGMESSAGECHAT_GUSUARIOTO\". The conflict occurred in database \"Base_12123\", table \"dbo.GMESSAGECHAT\", column 'CODUSUARIOTO'.\r\nThe statement has been terminated.\r\n\r\n--GlbUsuarioData\r\nDELETE GUSUARIO WHERE CODUSUARIO = '00001'",
"HelpUrl": "",
"Details": null
} |
5 - PATCH
5 - Patch (Atualizar alguns campos de um usuário)
5 - Patch
Configuração
Máscara de Url: http://{domínio}:{porta}/api/framework/v1/users/{id}
Exemplo de Configuração
Domínio: localhost
Porta: 8051
Id: Teste_01
Url Utilizada: http://localhost:8051/api/framework/v1/users/Teste_01
Exemplo de Entrada
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
{ "name":
{
"givenName": {{givenName_formatted}}
},
"emails": [
{
"value": {{email_formatted}},
"primary": true
}
],
"active": {{active}}
} |
Exemplo de Resultado Positivo
Resultado (JSON)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
|
{ "id": "Teste_01",
"meta": {
"resourceType": "User",
"created": "2018-12-05T15:03:07.28",
"lastModified": "2018-12-05T15:03:08.5546578"
},
"externalId": "IDTeste_01External",
"name": {
"formatted": "NOME SOCIAL DO TESTE_01",
"givenName": "Igor",
"familyName": "Automatizado"
},
"userName": "Teste_01",
"emails": [
{
"value": "igor@teste.com.br",
"primary": true
}
],
"active": true
} |
Saiba Mais:
Para mais informações sobre a API de Usuários, segue documentação abaixo:
API de Usuários
0 Comentários