Versão: 20 R9 BETA

Session

Os objetos de sessão são retornados pelo comando Session. These objects provide the developer with an interface allowing to manage the current user session and execute actions such as store contextual data, share information between session processes, launch session-related preemptive processes, or (web only) manage privileges.

Tipos de sessão

Os seguintes tipos de sessões são suportados por essa classe:

Sessões de usuário web: sessões de usuário web estão disponíveis quando sessões escaláveis estão habilitadas em seu projeto. Eles são usados para conexões Web e REST e podem receber privilégios.
Sessões de usuário cliente remoto: em aplicações cliente/servidor, os usuários remotos têm suas próprias sessões gerenciadas no servidor.
Sessão de procedimentos armazenados: Todos os procedimentos armazenados executados no servidor compartilham a mesma sessão de usuário virtual.
Standalone session: Objeto de sessão local retornado em aplicativo de usuário único (útil nas fases de desenvolvimento e teste de aplicativos cliente/servidor).

nota

A disponibilidade de propriedades e funções no objeto Session depende do tipo de sessão.

Resumo


.clearPrivileges() : Boolean removes all the privileges associated to the session and returns True if the execution was successful
.createOTP ( { lifespan : Integer } ) : Text cria um novo OTP (uma senha única) para a sessão e retorna seu UUID
.expirationDate : Text a data e a hora de expiração do cookie de sessão
.getPrivileges() : Collection returns a collection of all the privilege names associated to the session
.hasPrivilege( privilege : Text ) : Boolean retorna True se o privilege estiver associado à sessão e False caso contrário
.id : Text o identificador único (UUID) da sessão do usuário
.idleTimeout : Integer the inactivity session timeout (in minutes), after which the session is automatically closed by 4D
.info : Object descreve o cliente remoto ou a sessão do procedimento armazenado no servidor, ou a sessão autônoma
.isGuest() : Boolean returns True if the session is a Guest session (i.e. it has no privileges)
.restore ( token : Text ) : Boolean substitui a sessão do usuário da web pela sua sessão original correspondente ao token UUID
.setPrivileges( privilege : Text ) : Boolean .setPrivileges( privileges : Collection ) .setPrivileges( settings : Object ) : Boolean associa os privilégios e/ou papéis definidos no parâmetro para a sessão e retorna True se a execução foi bem sucedida
.storage : Object um objeto compartilhado que pode ser usado para armazenar informações disponíveis para todos os processos da sessão
.userName : Text o nome de usuário associado à sessão

.clearPrivileges()

História

Release	Mudanças
18 R6	Adicionado

.clearPrivileges() : Boolean

Parâmetro	Tipo		Descrição
Resultados	Parâmetros	<-	True se a execução for bem-sucedida

Descrição

nota

Esta função não faz nada e sempre retorna Verdadeiro com cliente remoto, procedimento armazenado e sessões autônomas.

The .clearPrivileges() function removes all the privileges associated to the session and returns True if the execution was successful. A menos que esteja no modo ["forceLogin"] (../REST/authUsers.md#force-login-mode), a sessão se torna automaticamente uma sessão de convidado.

nota

No modo "forceLogin", .clearPrivileges() não transforma a sessão em uma sessão Guest, apenas limpa os privilégios da sessão.

Exemplo

//Invalidate a web user session
var $isGuest : Boolean
var $isOK : Boolean

$isOK:=Session.clearPrivileges()
$isGuest:=Session.isGuest() //$isGuest is True

.createOTP()

História

Release	Mudanças
20 R9	Adicionado

.createOTP ( { lifespan : Integer } ) : Text

Parâmetro	Tipo		Descrição
lifespan	Integer	->	Session token lifespan in seconds
Resultados	Text	<-	UUID of the session

Descrição

nota

This function is only available with web user sessions. It returns an empty string in other contexts.

A função .createOTP() cria um novo OTP (uma senha única) para a sessão e retorna seu UUID. This token is unique to the session in which it was generated.

Para mais informações sobre os tokens OTP, consulte esta seção.

By default, if the lifespan parameter is omitted, the token is created with the same lifespan as the .idleTimeOut of the session. You can set a custom timeout by passing a value in seconds in lifespan (the minimum value is 10 seconds, lifespan is reset to 10 if a smaller value is passed). If an expired token is used to restore a web user session, it is ignored.

The returned token can then be used in exchanges with third-party applications or websites to securely identify the session. For example, the session OTP token can be used with a payment application.

Exemplo

var $token : Text
$token := Session.createOTP( 60 ) //o token é válido por 1 mn

.expirationDate

História

Release	Mudanças
18 R6	Adicionado

.expirationDate : Text

Descrição

nota

Essa propriedade só está disponível com sessões de usuário da Web.

A propriedade .expirationDate contém a data e a hora de expiração do cookie de sessão. The value is expressed as text in the ISO 8601 format: YYYY-MM-DDTHH:MM:SS.mmmZ.

Essa propriedade é somente leitura. Ele será automaticamente recalculado se o valor da propriedade .idleTimeout for modificado.

Exemplo

var $expiration : Text
$expiration:=Session.expirationDate //por exemplo "2021-11-05T17:10:42Z"

.getPrivileges()

História

Release	Mudanças
20 R6	Adicionado

.getPrivileges() : Collection

Parâmetro	Tipo		Descrição
Resultados	Collection	<-	Coleção de nomes de privilégios (strings)

Descrição

The .getPrivileges() function returns a collection of all the privilege names associated to the session.

Com cliente remoto, procedimento armazenado e sessões autônomas, essa função retorna uma coleção que contém apenas "WebAdmin".

info

Os privilégios são atribuídos a uma sessão usando a função setPrivileges().

Exemplo

O seguinte arquivo roles.json foi definido:

{
   "privileges":[
      {
         "privilege":"simple",
         "includes":[

         ]
      },
      {
         "privilege":"medium",
         "includes":[
            "simple"
         ]
      }
   ],
   "roles":[
      {
         "role":"Medium",
         "privileges":[
            "medium"
         ]
      }
   ],
   "permissions":{
      "allowed":[

      ]
   }
}

O papel de sessão é atribuído em uma função de datastore authentify():

  //Datastore Class

exposed Function authentify($role : Text) : Text
	Session.clearPrivileges()
	Session.setPrivileges({roles: $role})

Assuming the authentify() function is called with the "Medium" role:

var $privileges : Collection
$privileges := Session.getPrivileges()
//$privileges: ["simple","medium"]

Veja também

.setPrivileges()
Permissions – Inspect the privileges in the session for an easy debugging (blog post)

.hasPrivilege()

História

Release	Mudanças
18 R6	Adicionado

.hasPrivilege( privilege : Text ) : Boolean

Parâmetro	Tipo		Descrição
privilege	Text	->	Nome do privilegio a verificar
Resultados	Parâmetros	<-	True se a sessão tiver privilege, False caso contrário

Descrição

A função .hasPrivilege() retorna True se o privilege estiver associado à sessão e False caso contrário.

Com cliente remoto, procedimento armazenado e sessões autônomas, essa função sempre retorna True, independentemente do privilégio.

Exemplo

You want to check if the "WebAdmin" privilege is associated to the web user session:

If (Session.hasPrivilege("WebAdmin"))
	//Acesso é concedido, não faça nada
Else
	//Exibe uma página de autenticação

End if

.id

História

Release	Mudanças
20 R5	Adicionado

.id : Text

Descrição

A propriedade .id contém o identificador único (UUID) da sessão do usuário. Com o 4D Server, essa string exclusiva é atribuída automaticamente pelo servidor para cada sessão e permite que você identifique seus processos.

tip

Você pode usar essa propriedade para obter o objeto .storage de uma sessão graças ao comando storage.

.idleTimeout

História

Release	Mudanças

|v18 R6|Adicionado|

.idleTimeout : Integer

Descrição

nota

Essa propriedade só está disponível com sessões de usuário da Web.

The .idleTimeout property contains the inactivity session timeout (in minutes), after which the session is automatically closed by 4D.

Se não se definir esta propriedade, o valor padrão é 60 (1h).

Quando essa propriedade é definida, a propriedade .expirationDate é atualizada de acordo.

O valor não pode ser inferior a 60: se definir um valor inferior, o tempo de espera se eleva até 60.

Essa propriedade é leitura escrita.

Exemplo

If (Session.isGuest())
		// A Guest session will close after 60 minutes of inactivity
	Session.idleTimeout:=60
Else
		// Other sessions will close after 120 minutes of inactivity
	Session.idleTimeout:=120
End if

.info

História

Release	Mudanças
20 R5	Adicionado

.info : Object

Descrição

nota

Essa propriedade só está disponível com cliente remoto, procedimento armazenado e sessões autônomas.

A propriedade .info descreve o cliente remoto ou a sessão do procedimento armazenado no servidor, ou a sessão autônoma.

nota

O objeto .info é o mesmo objeto retornado na propriedade "session" pelo comando Process activity para sessões de procedimento armazenado e cliente remoto.
O objeto .info é o mesmo objeto retornado pelo comando Session info para uma sessão autônoma.

The .info object contains the following properties:

Propriedade	Tipo	Descrição
type	Text	Tipo de sessão: "remote", "storedProcedure", "standalone"
userName	Text	Nome de usuário 4D (o mesmo valor que `.userName`)
machineName	Text	Sessões remotas: nome da máquina remota. Sessão de procedimentos armazenados: nome da máquina do servidor. Sessão autônoma: nome da máquina
systemUserName	Text	Sessões remotas: nome da sessão do sistema aberta na máquina remota.
IPAddress	Text	Endereço IP da máquina remota
hostType	Text	Tipo de host: "windows" ou "mac"
creationDateTime	Date ISO 8601	Data e hora de criação da sessão. Sessão autônoma: data e hora da inicialização do aplicativo
state	Text	Estado da sessão: "ativa", "adiada", "em espera"
ID	Text	UUID da sessão (mesmo valor que `.id`)
persistentID	Text	Sessões remotas: ID persistente da sessão

nota

Since .info is a computed property, it is recommended to call it once and then to store it in a local variable if you want to do some processing on its properties.

.isGuest()

História

Release	Mudanças
18 R6	Adicionado

.isGuest() : Boolean

Parâmetro	Tipo		Descrição
Resultados	Parâmetros	<-	True se a sessão for uma sessão Guest, False caso contrário

Descrição

nota

Essa função sempre retorna False com cliente remoto, procedimento armazenado e sessões autônomas.

The .isGuest() function returns True if the session is a Guest session (i.e. it has no privileges).

Exemplo

No método base On Web Connection:

If (Session.isGuest())
	//Do something for Guest user
End if

.restore()

História

Release	Mudanças
20 R9	Adicionado

.restore ( token : Text ) : Boolean

Parâmetro	Tipo		Descrição
token	Text	->	Session token UUID
Resultados	Parâmetros	<-	True if the current session has been successfully replaced by the session in token

Descrição

nota

This function is only available with web user sessions. It returns False in other contexts.

A função .restore() substitui a sessão do usuário da web pela sua sessão original correspondente ao token UUID. Session's storage and privileges are restored.

If the original user session has been correctly restored, the function returns true.

The function returns false if:

the session token has already been used,
the session token has expired,
the session token does not exist,
the original session itself has expired.

In this case, the current web user session is left untouched (no session is restored).

Exemplo

In a singleton called by a custom HTTP Request handler:

shared singleton Class constructor()

Function callback($request : 4D.IncomingMessage) : 4D.OutgoingMessage
   Session.restore($request.urlQuery.state) 

Veja também

.createOTP()

.setPrivileges()

História

Release	Mudanças
19 R8	Suporte da propriedade "roles" das Settings
18 R6	Adicionado

.setPrivileges( privilege : Text ) : Boolean
.setPrivileges( privileges : Collection )
.setPrivileges( settings : Object ) : Boolean

Parâmetro	Tipo		Descrição
privilege	Text	->	Nome do privilégio
privileges	Collection	->	Collection de nomes de privilégios
settings	Object	->	Objetos com as propriedades "privilégios" (string ou collection)
Resultados	Parâmetros	<-	True se a execução for bem-sucedida

Descrição

nota

Essa função não faz nada e sempre retorna False com cliente remoto, procedimento armazenado e sessões autônomas.

A função .setPrivileges() associa os privilégios e/ou papéis definidos no parâmetro para a sessão e retorna True se a execução foi bem sucedida .

No parâmetro privilege, passe uma cadeia de caracteres contendo um nome de privilégio (ou vários nomes de privilégio separados por vírgula).
In the privileges parameter, pass a collection of strings containing privilege names.
In the settings parameter, pass an object containing the following properties:

Propriedade	Tipo	Descrição
privileges	Text ou Collection	String containing a privilege name, or Collection of strings containing privilege names
roles	Text ou Collection	String containing a role, or Collection of strings containing roles
userName	Text	Nome de usuário associado à sessão (opcional)

nota

Os privilégios e as funções são definidos no arquivo roles.json do projeto. Para obter mais informações, consulte a seção Privilégios.

Se a propriedade privileges ou roles tiverem um nome que não seja declarado no arquivo roles.json, ele será ignorado.

Como padrão quando não houver um privilégio associado à sessão, a sessão é uma Sessão de convidados.

A propriedade userName está disponível no nível do objeto de sessão (somente leitura).

Exemplo

Em um método de autenticação personalizado, deve estabecer o privilégio "WebAdmin" ao usuário:

var $userOK : Boolean

... //Authenticate the user

If ($userOK) //The user has been approved
  var $info : Object
  $info:=New object()
  $info.privileges:=New collection("WebAdmin")
  Session.setPrivileges($info)
End if

Veja também

.getPrivileges()

.storage

História

Release	Mudanças
20 R5	Support of remote client and stored procedure sessions
18 R6	Adicionado

.storage : Object

Descrição

A propriedade .storage contém um objeto compartilhado que pode ser usado para armazenar informações disponíveis para todos os processos da sessão.

Quando um objeto Session é criado, a propriedade .storage está vazia. Since it is a shared object, this property will be available in the Storage object of the server.

Like the Storage object of the server, the .storage property is always "single": adding a shared object or a shared collection to .storage does not create a shared group.

Essa propriedade é apenas de leitura, mas retorna um objeto de leitura e gravação.

tip

Você pode obter a propriedade .storage de uma sessão usando o comando Session storage.

Exemplo de sessão na web

Você deseja armazenar o IP do cliente na propriedade .storage. Você pode escrever no método de banco de dados On Web Authentication:

If (Session.storage.clientIP=Null) //first access
    Use (Session.storage)
        Session.storage.clientIP:=New shared object("value"; $clientIP)
    End use End if

Exemplo de sessão remota

Você deseja compartilhar dados entre processos na mesma sessão:

Use (Session.storage)
 Session.storage.settings:=New shared object("property"; $value; "property2"; $value2)
End use

.userName

História

Release	Mudanças
20 R5	Support of remote client and stored procedure sessions
18 R6	Adicionado

.userName : Text

Descrição

A propriedade .userName contém o nome de usuário associado à sessão. Pode usá-la para identificar o usuário dentro de seu código.

Com sessões da Web, essa propriedade é uma cadeia de caracteres vazia por padrão. Ele pode ser definido usando a propriedade privileges da função setPrivileges().
Com sessões de procedimento remotas e armazenadas, esta propriedade retorna o mesmo nome de usuário que o comando Current user.
Com sessões autônomas, essa propriedade contém "designer" ou o nome definido com o comando SET USER ALIAS.

Essa propriedade é somente leitura.

Tipos de sessão​

Resumo​

.clearPrivileges()​

Descrição​

Exemplo​

.createOTP()​

Descrição​

Exemplo​

.expirationDate​

Descrição​

Exemplo​

.getPrivileges()​

Descrição​

Exemplo​

Veja também​

.hasPrivilege()​

Descrição​

Exemplo​

.id​

Descrição​

.idleTimeout​

Descrição​

Exemplo​

.info​

Descrição​

.isGuest()​

Descrição​

Exemplo​

.restore()​

Descrição​

Exemplo​

Veja também​

.setPrivileges()​

Descrição​

Exemplo​

Veja também​

.storage​

Descrição​

Exemplo de sessão na web​

Exemplo de sessão remota​

.userName​

Descrição​

Tipos de sessão

Resumo

.clearPrivileges()

Descrição

Exemplo

.createOTP()

Descrição

Exemplo

.expirationDate

Descrição

Exemplo

.getPrivileges()

Descrição

Exemplo

Veja também

.hasPrivilege()

Descrição

Exemplo

.id

Descrição

.idleTimeout

Descrição

Exemplo

.info

Descrição

.isGuest()

Descrição

Exemplo

.restore()

Descrição

Exemplo

Veja também

.setPrivileges()

Descrição

Exemplo

Veja também

.storage

Descrição

Exemplo de sessão na web

Exemplo de sessão remota

.userName

Descrição