> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Multiplayer Session Directory
> Guia detalhado do MPSD que aborda atributos de modelos de sessão, o esquema do contrato v107, modelos de QoS, inicialização de membros e solução de problemas de multijogador.
Este artigo fornece uma visão geral da criação de sessões multijogador usando o serviço Multiplayer Session Directory (MPSD) dos serviços XBOX, em plataformas posteriores ao XBOX 360.
Este artigo é destinado principalmente aos desenvolvedores de títulos XBOX que enviam seus modelos de sessão diretamente ao Partner Center.
Este artigo aborda a configuração e o uso do MPSD e a solução de problemas de sessões multijogador.
**Conteúdo:**
* [Resumo da revisão](#rs)
* [Introdução](#intro)
* [Terminologia usada neste documento](#tuitd)
* [O Multiplayer Session Directory](#tmsd)
* [Sessões do MPSD](#mpsds)
* [Atributos do modelo de sessão](#sta)
* [Atualização do esquema do contrato](#csu)
* [Inicialização de membros em documentos de sessão](#miisd)
* [Sessão de tíquete de partida](#mts)
* [Modelos de Qualidade de Serviço (QoS)](#qost)
* [Detalhes da fase de QoS e da inicialização da sessão](#qospasid)
* [Sessão do XBOX Cloud Compute](#xccs)
* [Sessão bruta e propriedades personalizadas do título](#rsactp)
* Expiração de membros ativos
* [Perguntas frequentes e solução de problemas](#fat)
## Resumo da revisão
As bibliotecas da XBOX Services API (XSAPI) do lado do cliente usam atualmente a versão de contrato 104 ao se comunicar com os serviços do MPSD.
Esta versão do documento atualiza o esquema do modelo de sessão para a versão de contrato 107, que é a versão de contrato mais recente com suporte nos serviços do MPSD.
As alterações entre as versões 104 e 107 estão resumidas na seção [Atualização do esquema do contrato](#_Contract_schema_update) abaixo.
Observe que os modelos escritos para a versão de contrato 104 precisarão ser atualizados se forem republicados como 107.
No entanto, os serviços são compatíveis com versões anteriores, portanto você pode continuar usando as bibliotecas atuais, que serão atualizadas em uma versão futura.
A revisão anterior deste documento atualizou as informações sobre sessões de servidor e adicionou uma nova seção sobre XSAPIs e chamadas de serviço RESTful.
Além disso, a tabela da seção Consulta de informações de estado da sessão foi atualizada e a seção Modelos de Qualidade de Serviço (QoS) foi revisada.
## Introdução
Uma sessão multijogador é um documento seguro que fica na nuvem, no Multiplayer Session Directory (MPSD), e esse documento representa um grupo de pessoas jogando um jogo.
Especificamente, as sessões multijogador têm as seguintes características:
* Cada sessão tem um URI exclusivo.
* O documento de sessão contém os membros atuais, as configurações do jogo, os dados de inicialização e as informações do servidor de jogo.
* Os títulos criam e gerenciam suas próprias sessões.
* Uma sessão permite a conectividade entre seus membros.
O Multiplayer Session Directory (MPSD) centraliza os metadados da sessão de jogo em todos os clientes.
O MPSD fornece as informações básicas necessárias sobre uma sessão para ajudar a configurar as associações seguras de dispositivos entre os clientes.
O MPSD também fornece metadados básicos de primeira inicialização para que um cliente se conecte ao jogo antes de começar a trocar dados de jogo mais específicos.
Com o Process Lifetime Management (PLM) e a natureza de alternância de tarefas dos aplicativos no XBOX One e posteriores, o MPSD garante que os clientes tenham as informações corretas para contatar os pares e servidores identificados como parte da sessão de jogo ativa, e se coordena com o shell e o sistema operacional do console para reservar, ativar e gerenciar o tempo de vida do jogador em uma sessão de jogo.
## Terminologia usada neste documento
| Termo | Definição |
| - | - |
| Sessão multijogador | Um documento seguro que fica na nuvem dos serviços XBOX e representa um grupo de usuários que estão (ou estarão) conectados enquanto jogam um título no XBOX One ou posterior (incluindo PC). Todos os aspectos do multijogador, como matchmaking, parties, entrada em jogo em andamento e assim por diante, aproveitam a sessão multijogador. |
| Sessão de jogo | É a sessão de jogo propriamente dita, exposta no MPSD, na qual os usuários estão jogando juntos. Todos os cenários multijogador acabam resultando em uma sessão de jogo. |
| Sessão de tíquete de partida | É uma sessão usada para acompanhar o envio de tíquetes de partida durante o matchmaking. |
| Jogador inativo | Um jogador que foi definido com o estado Inativo na sessão. O título define um usuário com o estado Inativo quando o jogo está restrito, suspenso ou inativo de alguma outra forma, conforme definido pelo título. |
## O Multiplayer Session Directory
O MPSD facilita e ajuda os títulos a coordenar as informações de sessão entre jogadores online.
Diferentes tipos de sessões podem ser criados para realizar diferentes tarefas do jogo multijogador.
A tabela a seguir apresenta as diferenças entre como essas tarefas eram feitas no XBOX 360 e como são realizadas no XBOX One ou posterior (incluindo PC).
| Função ou tarefa | XBOX 360 | XBOX One ou posterior |
| - | - | - |
| **Obter informações da sessão de jogo** | **XSessionGetDetails**, **XSessionSearchByID** ou acompanhamento próprio. | Solicitar as informações da sessão ao serviço. |
| **Migrar o host** | Quando necessário, o título chama **XSessionMigrateHost.** | Não é necessário criar uma nova sessão, basta atribuir um novo host para SessionID. |
| **Gerenciar várias sessões de jogadores** | Complicado lidar com mais de uma sessão ao mesmo tempo. Por exemplo, **XNetReplaceKey** versus **XNetUnregisterKey**. | A sessão baseada em serviço torna o gerenciamento de uma sessão mais limpo e facilita lidar com várias sessões. |
| **Lidar com saídas e desconexões** | É preciso lidar com desconexões e saídas de forma diferente, com **XCloseHandle** ou **XSessionDelete**, respectivamente. | O serviço centralizado simplifica o tratamento de saídas e desconexões, e os tempos limite são definidos na configuração do jogo. |
### Padrões de sessão
* Sessões de jogo
* Sessão com os XUIDs dos jogadores, dados de endereço seguro do dispositivo e estados de propriedades. Ela é considerada a sessão de jogo propriamente dita.
* Pode ser ponto a ponto, ponto a host, ponto a servidor ou híbrida.
* Sessões de tíquete de partida
* Uma sessão enviada ao matchmaking para encontrar outros jogadores com quem jogar. Observe que uma sessão de jogo também pode ser uma sessão de tíquete, se o jogo estiver procurando mais jogadores.
* Sessões de servidor
* Sessões de jogo criadas e usadas por meio do processamento do XBOX Compute.
A Figura 1 ilustra os usos das sessões do MPSD, em que as caixas azuis representam as sessões do MPSD e as caixas vermelhas são os serviços que as utilizam.
**Figura 1. Uso de sessões do MPSD:** (figura ausente)
## Sessões do MPSD
As sessões mantêm duas listas de entidades relacionadas:
1. Membros (usuários) que entraram em uma sessão ou foram convidados para ela.
2. Servidores (servidores na nuvem ou servidores dedicados) que entraram na sessão.
Cada entidade tem:
1. Valores constantes definidos no momento da criação.
2. Propriedades mutáveis.
3. Metadados somente leitura.
### XSAPIs e chamadas de serviço RESTful
Há duas maneiras de interagir com os serviços de sessões e de matchmaking dos serviços XBOX.
* Chamadas HTTPS padrão
* Wrappers da XSAPI
#### Usando chamadas HTTPS padrão para os serviços RESTful
No XBOX One e posteriores, a primeira maneira de interagir com os serviços de sessões e de matchmaking dos serviços XBOX é usar chamadas HTTPS padrão para os URIs RESTful dos serviços XBOX.
Isso dá aos títulos flexibilidade para chamar e interagir com esses serviços, dependendo das configurações de servidor e de jogo.
Para obter uma lista desses URIs, veja a [Referência RESTful dos serviços XBOX](/pt-BR/reference/live/rest/atoc-xboxlivews-reference).
#### Usando os wrappers da XSAPI para serviços RESTful
A segunda maneira de interagir com os serviços de sessões e de matchmaking é usar as XSAPIs, que atuam como wrappers para os URIs dos serviços RESTful.
Elas permitem uma abordagem mais tradicional de uso de APIs no código, sem precisar lidar com o tráfego HTTPS em cada chamada.
Para obter mais informações sobre as XSAPIs, veja a [página do xbox-live-api no GitHub](https://github.com/microsoft/xbox-live-api).
Essa documentação de referência inclui:
* Referência da API de análise de JSON - Material de referência para as APIs de análise de JSON.
* Namespace Windows.Web - Membros do namespace Windows.Web.
* Referência do SDK do XBOX Compute - APIs para criar instâncias de servidor de jogo para o XBOX Compute.
### Sessões e modelos do MPSD
As sessões do MPSD são criadas com modelos ingeridos por meio do Partner Center.
Os modelos são documentos JSON que definem a estrutura da sessão que está sendo criada.
O modelo fornece as constantes para a nova sessão.
O trecho a seguir é um exemplo de configuração de modelo.
```json theme={null}
// Used for creating the session that you then pass into your match ticket request. This *should* not have any QoS requirements.
MatchTicketSession (Contract Version: 107)
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 10,
"visibility": "private",
"capabilities": {},
"memberInitialization": {
"joinTimeout": 20000,
"externalEvaluation": false,
"membersNeededToStart": 1
}
},
"custom": {}
}
}
// This is the new game session that is returned after you've been matched.
// Note: This is used for in-game QoS. For out-of-game QoS, you will need P2P/HTP requirements.
GameSession (Contract Version:107)
{
"constants": {
"system": {
"maxMembersCount": 12,
"capabilities": {"connectivity": true }
},
"memberInitialization": {
"joinTimeout": 20000,
"measurementTimeout": 15000,
"externalEvaluation": false,
"membersNeededToStart": 4
},
"custom": {}
}
}
```
A sessão de tíquete de partida deve ser usada com um modelo de sessão de jogo configurado com valores de tempo limite de QoS em seu objeto **memberInitialization**.
**Figura 2. Hopper de exemplo:**
O trecho de código a seguir é um exemplo de modelo de sessão de jogo ponto a ponto (QoS gerenciado pelo título).
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 10,
"visibility": "private",
"capabilities": {
"connectivity": true
},
"memberInitialization": {
"joinTimeout": 20000,
"externalEvaluation": false,
"membersNeededToStart": 2
}
},
"custom": {}
}
}
```
Este é um exemplo de sessão ponto a servidor e de modelo RAW.
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 10,
"visibility": "private",
"capabilities": {}
},
"custom": {}
}
}
```
O código a seguir mostra um exemplo de modelo de sessão de tíquete de partida, que é usado para o Smart Match.
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 10,
"visibility": "private",
"capabilities": {},
"memberInitialization": {
"joinTimeout": 20000,
"externalEvaluation": false,
"membersNeededToStart": 1
}
},
"custom": {}
}
}
```
### Verificando quais modelos estão configurados para o seu SCID
#### Modelos de sessão
A lista de modelos de sessão existentes em um SCID, bem como os detalhes de um modelo de sessão específico, pode ser recuperada do MPSD:
```uri theme={null}
GET /serviceconfigs/{scid}/sessiontemplates
GET /serviceconfigs/{scid}/sessiontemplates/{session-template-name}
```
#### Consulta de informações de estado da sessão
As sessões podem ser consultadas nos níveis de configuração de serviço e de modelo de sessão:
```uri theme={null}
GET /serviceconfigs/{scid}/sessions
GET /serviceconfigs/{scid}/sessiontemplates/{session-template-name}/sessions
```
Por padrão, isso retornará até 100 sessões não privadas.
A consulta pode ser modificada usando estes parâmetros de cadeia de consulta:
| Cadeia de consulta | Efeito | Descrição |
| - | - | - |
| keyword=foo | Incluir apenas sessões que tenham a palavra-chave "foo". | |
| XUID=123 | Incluir apenas sessões nas quais o usuário "123" está. | Por padrão, o usuário deve estar ativo na sessão para que ela seja incluída. |
| *reservations*=**true** | Incluir sessões nas quais o usuário está definido como jogador reservado, mas ainda não entrou para se tornar um jogador ativo. | Somente ao consultar suas próprias sessões ou ao consultar as sessões de um usuário específico de servidor para servidor. |
| *inactive*=**true** | Incluir sessões que o usuário aceitou, mas nas quais não está jogando ativamente. | Sessões nas quais o usuário está "ready", mas não "active", contam como inativas. |
| *private*=**true** | Incluir sessões privadas. | Somente ao consultar suas próprias sessões ou ao consultar de servidor para servidor. |
| *visibility*=open | Incluir apenas sessões que estejam "open". | Se definido como "private", a diretiva "private=true" também deverá ser definida. |
| *take*=5 | Retornar até cinco sessões. | Deve estar entre 0 e 100. |
O resultado é uma matriz JSON de referências de sessão.
Alguns dados da sessão são incluídos embutidos.
**Observação** Toda consulta deve incluir um filtro de palavra-chave, um filtro de XUID ou ambos.
Definir *private* (que retorna sessões privadas) ou *reservations* (que retorna sessões nas quais o usuário não entrou) como **true** exige que o chamador tenha acesso de nível de servidor à sessão ou que a declaração de XUID do chamador corresponda ao filtro de XUID no URI.
Caso contrário, será retornado 403 Forbidden (independentemente de essas sessões existirem ou não).
O trecho de código a seguir mostra um exemplo de resposta de consulta.
```json theme={null}
{
"results": [ {
"xuid": "9876", // If the session was found from a xuid, that xuid.
"startTime": "2009-06-15T13:45:30.0900000Z",
"sessionRef": {
"scid": "foo",
"templateName": "bar",
"name": "session-seven"
},
"accepted": 4, // Approximate number of non-reserved members.
"status": "active", // or "reserved" or "inactive". This is the state of the user in the session, not the session itself. Only present if the session was found using a xuid.
"visibility": "open", // or "private", "visible", or "full"
"myTurn": true, // Not present is the same as 'false'. Only present if the session was found using a xuid.
"keywords": [ "one", "two" ]
} ]
}
```
## Atributos do modelo de sessão
## Atualização do esquema do contrato
Conforme mencionado no início deste documento, a versão de contrato de modelo de sessão mais recente é a 107, que introduz algumas alterações no esquema em relação à versão anterior, 104.
Os modelos escritos para a versão de contrato 104 precisarão ser atualizados se forem republicados como 107.
A seguir está um resumo das alterações.
* **/constants/system/managedInitialization** foi renomeado para **/constants/system/memberInitialization**.
* O campo **autoEvaluate** foi renomeado para **externalEvaluation** e sua polaridade mudou, exceto que **false** continua sendo o padrão.
* O valor padrão de **membersNeededToStart** mudou de 2 para 1.
* O valor padrão de **joinTimeout** mudou de 5 segundos para 10 segundos.
* O padrão de **measurementTimeout** mudou de 5 segundos para 30 segundos.
* **/constants/system/timeouts** foi removido, e os tempos limite foram renomeados e realocados em **/constants/system**.
* O tempo limite **reserved** passa a ser **reservedRemovalTimeout**.
* O tempo limite **inactive** passa a ser **inactiveRemovalTimeout** e seu novo padrão é 0 em vez de 2 horas.
* O tempo limite **ready** passa a ser **readyRemovalTimeout**.
* O tempo limite **sessionEmpty** passa a ser **sessionEmptyTimeout**.
* **/constants/system/capabilities/gameplay** deve ser especificado como **true** em sessões que representam jogo real (em oposição a sessões auxiliares, como sessões de partida e de lobby) para habilitar os jogadores recentes e os relatórios de reputação.
### Objetos do sistema
Cada um dos objetos do sistema no documento de sessão tem um esquema fixo que é imposto e interpretado pelo MPSD.
No corpo das solicitações PUT, os objetos do sistema são validados e mesclados da mesma forma que os objetos personalizados.
Mas, ao contrário dos objetos personalizados, depois de mesclados, os objetos do sistema são validados novamente e processados com base nesses esquemas.
**/constants/system**
```json theme={null}
{
"version": 1, //Document Version (FAL release version 1, service contract 107)
"maxMembersCount": 100, // Defaults to 100 if not set on creation. Must be between 1 and 100.
"visibility": "private", // Or "visible" or "open", defaults to "open" if not set on creation.
"initiators": [ "1234" ], // If specified on a new session, the creators xuid must be in the list (or the creator must be a server).
"inviteProtocol": "party", // Optional URI scheme of the launch URI for invite toasts.
"reservedRemovalTimeout": 10000, // Default is 30 seconds. Member is removed from the session.
"inactiveRemovalTimeout": 0, // Default is zero. Member is removed from the session.
"readyRemovalTimeout": 60000, // Default is three minutes. Member is removed from the session.
"sessionEmptyTimeout": 0, // Default is zero. Session is deleted.
// Capabilities are boolean values that are optionally set in the session template. If no capabilities are needed, an empty "capabilities" object should be in the template in order to prevent capabilities from being specified on session creation, unless the title desires dynamic session capabilities.
"capabilities": {
"clientMatchmaking": true,
"connectivity": true, // Cannot be set if 'large' is specified.
"suppressPresenceActivityCheck": false,
"gameplay": false,
"large": false
},
/* If a "memberInitialization" object is set, the session expects the client system or title to perform initialization following session creation and/or as new members join the session. The timeouts and initialization stages are automatically tracked by the session, including QoS measurements if any metrics are set. These timeouts override the session's reservation and ready timeouts for members that have 'initializationEpisode' set. */
"memberInitialization": {
"joinTimeout": 20000, // Milliseconds. Unspecified counts as 10 seconds.
"externalEvaluation": false,
"membersNeededToStart": 2 // Unspecified counts as 1. Must be between 0 and maxMembersCount. Only applies to episode 1. If 00 and the session is created with no members to initialize, episode 1 is skipped..
},
```
**/properties/system**
```json theme={null}
{
// Optional array of case-insensitive strings. Cannot be set if the session's visibility is "private".
"keywords": [ "hello" ],
// Array of integer indices of members whose turn it is. Defaults to empty. Can't be set (and doesn't appear) on large sessions.
"turn": [ 0 ],
/* Restricts who can join "open" sessions. (Has no effect on reservations, which means it has no impact on "private" and "visible" sessions.) Defaults to "none". On large sessions, "none" is the only valid value.
If "local", only users whose token's DeviceId matches someone else already in the session and "active": true.
If "followed", only local users (as defined above) and users who are followed by an existing (not reserved) member of the session can join without a reservation. */
"joinRestriction": "none",
// Device token of the host. Must match the "deviceToken" of at least one member, otherwise this field is deleted.
// If "peerToHostRequirements" is set and "host" is set, the measurement stage assumes the given host is the correct host and only measures metrics to that host.
// Can't be set on large sessions.
"host": "99e4c701",
// Can only be set while "initializing/stage" is "evaluating". True indicates success, and false indicates failure. Once set, "initializing/stage" is immediately updated, and this field is removed.
"initializationSucceeded": true,
/* The ordered list of case-insensitive connection strings that the session could use to connect to a game server. Generally titles should use the first on the list, but sophisticated titles could use a custom mechanism (e.g. Thunderhead) for choosing one of the others (e.g. based on load). */
"serverConnectionStringCandidates": [ "datacenter b", "serverfarm a" ],
"matchmaking": {
"targetSessionConstants": { },
// Force a specific connection string to be used (useful in preserveSession=always cases).
"serverConnectionString": "datacenter b",
},
// True if the match that was found didn't work out and needs to be resubmitted. Set to false to signal that the match did work, and the matchmaking service can release the session.
"matchmakingResubmit": true
}
```
### Tempos limite
As sessões podem ser alteradas por temporizadores e outros eventos externos.
O objeto **Timeouts** no MPSD fornece um mecanismo básico para gerenciar o tempo de vida e os membros da sessão.
O campo **nextTimer** da sessão informa o horário do próximo temporizador.
Os clientes podem usar essas informações para escolher um bom intervalo para a próxima sondagem.
Esse valor também é retornado no cabeçalho HTTP **Expires**.
Os tempos limite são especificados em milissegundos.
Zero é permitido e significa que o tempo limite deve ser imediato.
Se um determinado tempo limite não for especificado, ele será considerado infinito.
Como os tempos limite têm padrões, o modelo de sessão deve especificar explicitamente "null" para um tempo limite infinito.
#### SessionEmptyTimeout
O valor **/constants/system/sessionEmptyTimeout** configura o número de milissegundos após uma sessão ficar vazia para que ela seja excluída.
O padrão é zero, o que significa que a sessão será excluída imediatamente.
Se o valor não for especificado, as sessões vazias continuarão existindo indefinidamente.
#### Tempos limite de membros
Os outros três tempos limite em **/constants/system** controlam por quanto tempo um membro pode permanecer em um determinado estado:
* **reservedRemovalTimeout**
* A reserva é excluída quando o tempo limite expira. O padrão é 30 segundos.
* **inactiveRemovalTimeout**
* Um membro inativo é removido da sessão após duas horas, por padrão.
* **readyRemovalTimeout**
* Os membros que estão "ready" voltam ao estado inativo após três minutos, por padrão.
## Inicialização de membros em documentos de sessão
### Inicialização de membros
O objeto **memberInitialization** controla os estágios de inicialização após a criação da sessão e/ou à medida que novos membros entram na sessão.
Os tempos limite e os estágios de inicialização são acompanhados automaticamente pela sessão, incluindo as medições de QoS se houver métricas definidas.
Esses tempos limite substituem os tempos limite de reserva e de "ready" da sessão para os membros que têm a propriedade **initializationEpisode** definida.
Exemplo:
```json theme={null}
"memberInitialization": {
"joinTimeout": 5000,
"measurementTimeout": 5000,
"evaluationTimeout": 5000, // only specify for external evaluation
"externalEvaluation": true,
"membersNeededToStart": 2
},
```
**Figura 3. Fluxo de inicialização de membros:**
Cada um dos três estágios de inicialização de membros pode atingir o tempo limite:
1. **joiningTimeout**
* O tempo, em milissegundos, que os usuários têm para entrar na sessão. As reservas dos membros que não conseguirem entrar são removidas.
2. **measuringTimeout**
* O tempo que os membros têm para enviar suas medições. Os membros que não conseguirem enviar as medições são marcados com um *failureReason* de "timeout".
3. **evaluationTimeout**
* O tempo que um membro tem para tomar e enviar a decisão de avaliação. Se nenhuma decisão for recebida, isso contará como falha.
**externalEvaluation**
* O MPSD pode fazer uma avaliação automática de QoS com base nos requisitos fornecidos no modelo de sessão. A avaliação é realizada quando externalEvaluation está definido como false. **externalEvaluation** precisa ser **true** quando um **evaluationTimeout** é definido. Se houver dois requisitos ponto a ponto ou ponto a host, você ainda deverá definir **externalEvaluation** como **false** para que a sessão conclua a inicialização automaticamente.
**membersNeededToStart**
* É o número mínimo de reservas de membros que precisam existir com "initialize":"true" e passar no QoS para que a avaliação automática seja bem-sucedida.
### Episódios de inicialização
Quando o objeto **memberInitialization** é definido, o MPSD avança as fases de inicialização por episódio.
O primeiro episódio é iniciado quando a sessão é criada e incluirá todas as fases definidas no modelo.
Todos os novos membros convidados ou que entrarem enquanto um episódio já estiver em andamento serão marcados para o próximo episódio.
O status de um episódio ou do **memberInitialization** em geral pode ser recuperado do objeto **initializing** da sessão.
**Observação** Esteja ciente de que esse objeto é removido após a conclusão da inicialização.
Exemplo:
```json theme={null}
"initializing": {
"stage": "measuring",
"stageStartTime": "2009-06-15T13:45:30.0900000Z",
"episode": 1
},
```
O estágio vai de joining para measuring e para evaluating.
Se um episódio falhar, o estágio será definido como *failed* e a sessão não poderá ser inicializada.
Caso contrário, quando um episódio de inicialização for concluído, o objeto **initializing** será removido.
As falhas de inicialização também podem ser acompanhadas para cada membro.
Elas são definidas na transição para fora do estágio joining ou measuring se esse membro não passar.
Exemplo:
```json theme={null}
"initializationFailure": "latency",
```
Em ordem de precedência, o valor desse atributo pode ser definido como *timeout, latency, bandwidthdown, bandwidthup, network, group* ou *episode*.
O valor network significa que a configuração e/ou as condições de rede (como conflito de conversão de endereços de rede \[NAT]) impediram a medição das métricas de QoS.
O único valor possível ao final de joining é *group*.
(Ao atingir o tempo limite em joining, a reserva é removida.)
Se **memberInitialization** estiver definido e o membro tiver sido adicionado com "initialize": true, isso será definido como o episódio de inicialização do qual o membro participará. O valor 1 é usado para os membros adicionados a uma nova sessão no momento em que ela é criada, e é removido quando o episódio de inicialização termina.
```json theme={null}
"initializationEpisode": 1,
```
## Match ticket session
Quando uma sessão do MPSD está sendo usada como sessão de tíquete de partida, algumas propriedades e constantes especiais da sessão são usadas.
**/members/{index}/constants/system**
```json theme={null}
{
{
"xuid": "12345678",
"initialize": "false", // Run initialization for this user (if "memberInitialization" is set). Defaults to false.
```
Quando o serviço de matchmaking adiciona usuários a uma sessão, ele fornece algum contexto sobre como e por que eles foram combinados na sessão, no campo **matchmakingResult**.
```json theme={null}
"matchmakingResult": {
```
Esta é uma cópia das **serverMeasurements** de um usuário da sessão de matchmaking.
```json theme={null}
"serverMeasurements": {
"east.thunderhead.azure.com": {
"latency": 233 // Milliseconds
}
}
}
}
```
## Modelos de Qualidade de Serviço (QoS)
Para modelos de sessão de jogo, podem ser adicionados valores que informam ao MPSD que ele deve se coordenar com a camada de rede e com os recursos sociais do console.
O objetivo dessa coordenação é validar a qualidade do estado da conexão antes que uma sessão seja criada e antes que um usuário seja informado de que o jogo está pronto para receber entradas.
O trecho de código a seguir é um exemplo de modelo de sessão de jogo ponto a host com QoS:
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 20,
"visibility": "private",
"capabilities": {
"connectivity": true
},
"memberInitialization": {
"joinTimeout": 20000,
"externalEvaluation": false,
"membersNeededToStart": 1
},
"peerToHostRequirements": {
"latencyMaximum": 350,
"bandwidthDownMinimum": 1000,
"bandwidthUpMinimum": 100,
"hostSelectionMetric": "latency"
}
},
"custom": {}
}
}
```
Este trecho de código é um exemplo de modelo de sessão de jogo ponto a ponto com QoS:
```json theme={null}
{
"constants": {
"system": {
"version": 1,
"maxMembersCount": 20,
"visibility": "private",
"capabilities": {
"connectivity": true
},
"memberInitialization": {
"joinTimeout": 20000,
"externalEvaluation": false,
"membersNeededToStart": 1
},
"peerToPeerRequirements": {
"latencyMaximum": 250,
"bandwidthMinimum": 10000
}
},
"custom": {}
}
}
```
### Atributos do modelo de sessão com QoS
Se um objeto **memberInitialization** estiver definido, a sessão esperará que o sistema cliente ou o título realize a inicialização após a criação da sessão e/ou à medida que novos membros entrarem na sessão.
Os tempos limite e os estágios de inicialização são acompanhados automaticamente pela sessão, incluindo as medições de QoS se houver métricas definidas.
Esses tempos limite substituem os tempos limite de reserva e de "ready" da sessão para os membros que têm a propriedade **initializationEpisode** definida.
```json theme={null}
"memberInitialization": {
"joinTimeout": 5000, // Milliseconds. Unspecified counts as 10 seconds.
"measurementTimeout": 5000, // Milliseconds. Unspecified counts as 30 seconds.
"evaluationTimeout": 5000, // Milliseconds. Can only be set if 'externalEvaluation' is true. Unspecified counts as 5 seconds.
"externalEvaluation": true,
"membersNeededToStart": 2 // Unspecified counts as 1. Must be between 0 and maxMembersCount. Only applies to episode 1. If 0 and the session is created with no members to initialize, episode 1 is skipped.
},
```
Uma sessão de jogo com QoS exige a funcionalidade de conectividade.
Se nenhuma métrica for especificada, o padrão será o necessário para atender aos requisitos de QoS.
Se forem especificadas, elas deverão ser suficientes para atender aos requisitos de QoS.
```json theme={null}
"metrics": {
"latency": true,
"bandwidthDown": true,
"bandwidthUp": true,
"custom": true
```
Os limites a seguir se aplicam a cada conexão entre pares de todos os membros de uma sessão:
```json theme={null}
"peerToPeerRequirements": {
"latencyMaximum": 250, // Milliseconds
"bandwidthMinimum": 10000 // Kilobits per second
},
```
Os limites a seguir se aplicam a cada conexão de um candidato a host:
```json theme={null}
"peerToHostRequirements": {
"latencyMaximum": 250, // Milliseconds
"bandwidthDownMinimum": 100000, // Kilobits per second
"bandwidthUpMinimum": 1000, // Kilobits per second
"hostSelectionMetric": "bandwidthup" // Or "bandwidthdown" or "latency". Not specified is the same as "latency".
},
```
As seguintes cadeias de conexão de servidor em potencial devem ser avaliadas (observe que as cadeias de conexão devem estar em letras minúsculas):
```json theme={null}
"measurementServerAddresses": {
"east.thunderhead.azure.com": {
"secureDeviceAddress": "r5Y=" // Base-64 encoded secure-device-address
},
"west.thunderhead.azure.com": {
"secureDeviceAddress": "rwY="
}
}
}
```
**members/{index}/properties/system**
Esses sinalizadores controlam o status do membro e **activeTitle**, e são mutuamente exclusivos (é um erro definir ambos como **true**).
Para cada um, **false** é o mesmo que "não presente". O status padrão é "inactive", ou seja, nenhum dos dois está presente.
```json theme={null}
"ready": true,
"active": false,
// Base-64 blob, or not present. Empty-string is the same as not present.
// 'capabilities/connectivity' must be enabled in order for this to be set.
"secureDeviceAddress": "ryY=",
// List of members in my group, by index. Each element must be an integer 0 <= n < 'membersInfo/next'.
// During member initialization, if any members in the list fail, this member will also fail.
"group": [ 5 ],
// QoS measurements by lower-case device token.
// Like all fields, "measurements" must be updated as a whole. It should be set once when measurement is complete, not incrementally.
// Metrics can me omitted if they weren't successfully measured, i.e. the peer is unreachable.
// If a "measurements" object is set, it can't contain an entry for the member's own address.
"measurements": {
"e69c43a8": {
"latency": 5953, // Milliseconds
"bandwidthDown": 19342, // Kilobits per second
"bandwidthUp": 944, // Kilobits per second
"custom": { }
}
},
// QoS measurements by game-server connection string. Like all fields, "serverMeasurements" must be updated as a whole, so it should be set once when measurement is complete.
// If empty, it means that none of the measurements completed within the "serverMeasurementTimeout".
"serverMeasurements": {
"east.thunderhead.azure.com": {
"latency": 233 // Milliseconds
}
},
// Subscriptions for shoulder taps on session changes. The 'profile' indicates which session changes to tap as well as other properties of the registration like the min time between taps.
// The subscription is named with a client-generated GUID that is also sent back with the tap as a context ID.
// Subscriptions can be added and removed individually, without affecting other subscriptions in the "subscriptions" object.
// To remove a subscription, set its context ID to null.
// (Like the "ready" and "active" flags, the "subscriptions" data is copied out and maintained internally, so the normal replace-all rule on system fields doesn't apply to "subscriptions".)
"subscriptions": {
"961dc162-3a8c-4982-b58b-0347ed086bc9": {
"profile": "party", // Or "matchmaking", "initialization", "roster", "queueHost", or "queue"
"onBehalfOfTitleId": "3948320593", // Optional decimal title ID of the registered channel. If not set the title ID is taken from the token.
},
"709fef70-4638-4b94-905b-24cb02706eb5": null
}
}
```
## Detalhes da fase de QoS e da inicialização da sessão
O MPSD acompanhará e relatará os resultados de QoS para a criação do jogo depois que o modelo concluir a inicialização de membros.
O progresso dessa operação será representado por um objeto *initializing* no documento de sessão, conforme descrito na seção [Inicialização de membros](#_Member_initialization_in) acima.
O objeto *initializing* tem um atributo *stage*, que representa o estágio atual da inicialização.
O estágio avança de *joining* para *measuring* e para *evaluating*.
* Se o episódio de inicialização #1 falhar, o estágio será definido como *failed* e a sessão não poderá ser inicializada. Caso contrário, quando um episódio de inicialização for concluído, o objeto "initializing" será removido. Se **externalEvaluation** estiver definido como **false**, o estágio evaluating será ignorado. Se nem **metrics** nem **measurementServerAddresses** estiverem definidos, o estágio measuring será ignorado.
```json theme={null}
"initializing": {
"stage": "measuring",
"stageStartTime": "2009-06-15T13:45:30.0900000Z",
"episode": 1
},
```
* Os candidatos a host são tokens de dispositivo listados em ordem de preferência. Eles são definidos após o estágio *measuring* do episódio de inicialização #1 se **peerToHostRequirements** estiver definido e **/properties/system/host** não estiver. Eles são limpos depois que um objeto **/properties/system/host** é definido.
```json theme={null}
"hostCandidates": [ "ab90a362", "99582e67" ],
"constants": { /* Property Bag */ },
"properties": { /* Property Bag */ },
"members": {
"1": {
"constants": { /* Property Bag */ },
"properties": { /* Property Bag */ },
```
* O atributo *gamertag* só será definido se o membro tiver aceitado e se uma declaração de gamertag tiver sido encontrada para esse membro.
```json theme={null}
"gamertag": "stacy",
```
* O atributo *deviceToken* é definido quando o membro envia um endereço seguro do dispositivo. É uma cadeia de caracteres que não diferencia maiúsculas de minúsculas e pode ser usada para comparações de igualdade.
```json theme={null}
"deviceToken": "9f4032ba7",
```
* O valor *reserved* é removido depois que o usuário executa sua primeira solicitação PUT para o documento de sessão. Quando os jogadores estão reservados, isso significa que foram convidados para a sessão de jogo, mas ainda não aceitaram nem tiveram suas conexões avaliadas.
```json theme={null}
"reserved": true,
```
* Se o membro estiver ativo, *activeTitleId* será o título no qual o membro está ativo, em decimal.
```json theme={null}
"activeTitleId": "8397267",
```
* Esse atributo se refere ao horário em que o usuário entrou na sessão. Se *reserved* for **true**, *joinTime* será o horário em que a reserva foi feita.
```json theme={null}
"joinTime": "2009-06-15T13:45:30.0900000Z",
```
* Presente se esse membro estiver na matriz properties/system/turn; caso contrário, ausente.
```json theme={null}
"turn": true,
```
* O atributo *initializationFailure* é definido no objeto do membro na transição para fora do estágio joining ou measuring se o membro não tiver passado no estágio com êxito. Em ordem de precedência, ele pode ser definido como *timeout*, *latency*, *bandwidthdown*, *bandwidthup*, *network*, *group* ou *episode*.
O valor *network* significa que a configuração e/ou as condições de rede (como conflitos de conversão de endereços de rede \[NATs]) impediram a medição das métricas de QoS. O único valor possível ao final de joining é *group*. (Ao atingir o tempo limite em joining, a reserva é removida.) O valor *episode* é definido após uma falha no estágio "evaluation" em todos os membros do episódio de inicialização que não falharam durante joining ou measuring.
```json theme={null}
"initializationFailure": "latency",
```
* Se **memberInitialization** estiver definido e o membro tiver sido adicionado com "initialize": true, isso será definido como o episódio de inicialização do qual o membro participará. O valor 1 é usado para os membros adicionados a uma nova sessão no momento da criação. É removido quando o episódio de inicialização termina.
```json theme={null}
"initializationEpisode": 1,
```
* O atributo *next* representa o valor de índice do próximo membro na sessão. Ele terá o mesmo valor do atributo *next* no objeto **membersInfo** abaixo se não houver mais membros a adicionar.
```json theme={null}
"next": 4
},
"4": { "next": 5 /* etc */ }
},
"membersInfo": {
"first": 1, // The first member's index.
"next": 5, // The index that the next member added will get.
"count": 2, // The number of members.
"accepted": 1 // The number of members that are no longer 'pending'.
},
"servers": {
"name": {
"constants": { /* Property Bag */ },
"properties": { /* Property Bag */ }
}
}
}
```
## Sessão do XBOX Cloud Compute (preterida)
Uma sessão do XBOX Cloud Compute contém a lista ordenada de cadeias de conexão, sem diferenciação de maiúsculas e minúsculas, que a sessão pode usar para se conectar a um servidor de jogo.
Geralmente, os títulos devem usar a primeira cadeia da lista, mas títulos sofisticados podem usar um mecanismo personalizado para escolher uma das outras (por exemplo, com base na carga).
```json theme={null}
"serverConnectionStringCandidates": [ "west.thunderhead.azure.com", "east.thunderhead.azure.com" ],
"matchmaking": {
"clientResult": { // Requires the clientMatchmaking property.
"status": "searching", // Or "expired", "found", "failed", or "canceled".
"statusDetails": "Description", // Default is empty string.
"typicalWait": 30, // The expected number of seconds waiting as a non-negative integer.
"targetSessionRef": {
"scid": "1ECFDB89-36EB-4E59-8901-11F7393689AE",
"templateName": "capture-the-flag",
"name": "2D58F65F-0E3C-4F1F-8277-2BC9873FDB23"
}
},
"targetSessionConstants": { },
// Force a specific connection string to be used (useful in preserveSession=always cases).
"serverConnectionString": "west.thunderhead.azure.com",
// True if the match that was found didn't work out and needs to be resubmitted. Set to false
// to signal that the match did work, and the matchmaking service can release the session.
"resubmit": true
}
}
```
\*\*/servers/{server-name}/properties/system \*\*
```json theme={null}
{
"lockId": "opaque56789", // If set, a matchmaking service is servicing this session.
"status": "searching", // Or "expired", "found", "failed", or "canceled". Optional.
"statusDetails": "Description", // Optional free-form text. Default is empty string.
"typicalWait": 30, // Optional. The expected number of seconds waiting as a non-negative integer.
"targetSessionRef": { // Optional.
"scid": "1ECFDB89-36EB-4E59-8901-11F7393689AE",
"templateName": "capture-the-flag",
"name": "2D58F65F-0E3C-4F1F-8277-2BC9873FDB23"
}
}
```
## Sessão bruta e propriedades personalizadas do título
Uma sessão pode ser usada para armazenar informações administrativas personalizadas (metadados) sobre um jogo multijogador.
Os dados do jogo ou as informações salvas devem ser armazenados no TMS++.
### Recipientes de propriedades
Cada um dos objetos acima marcados como recipiente de propriedades consiste em dois objetos internos opcionais, system e custom.
Os objetos custom podem conter qualquer JSON.
```json theme={null}
"custom": {
"myField1": true,
"myField2": "string",
"myField3": 5.5,
"myField4": { "myObject": null },
"myField5": [ "my", "array" ]
}
```
## Expiração de membros ativos
Os membros ativos são marcados automaticamente como inativos quando o MPSD detecta que o usuário não está mais envolvido com o título.
Isso pode acontecer, por exemplo, se a Presença atingir o tempo limite do registro do usuário.
Esse mecanismo é apenas uma salvaguarda; ou seja, os títulos ainda são obrigados a marcar proativamente os membros como inativos (ou removê-los da sessão) quando os membros saem ou alternam para fora do título, se desconectam ou deixam de estar envolvidos de alguma outra forma.
## Perguntas frequentes e solução de problemas
### Como faço para chamar o MPSD?
Usando autenticação por certificado: client-sessiondirectory.xboxlive.com
Exemplo:
```uri theme={null}
PUT https://client-sessiondirectory-stress.xboxlive.com/serviceconfigs/8cvda84-2606-4bab-8eda-d12313e65143/sessiontemplates/teamDeathmatch/sessions/3baafc35-816d-49cd-9656-5772506c988a
```
Usando autenticação por XToken: sessiondirectory.xboxlive.com
Exemplo:
```uri theme={null}
PUT https://sessiondirectory-stress.xboxlive.com/serviceconfigs/8cvda84-2606-4bab-8eda-d12313e65143/sessiontemplates/teamDeathmatch/sessions/3baafc35-816d-49cd-9656-5772506c988a
```
### Como descubro qual SCID, modelo de sessão e sandbox devo usar?
Essas informações podem ser encontradas no Partner Center para o seu título.
Se você ainda não tiver acesso ao Partner Center, entre em contato com seu gerente de conta de desenvolvedor, que poderá ajudar a obter as informações para você.
### Existe um exemplo de corpo de solicitação com o qual eu possa comparar o meu?
### Estou recebendo um erro 404 ao chamar o MPSD.
Colete rastreamentos do Fiddler para obter mais informações e, em seguida, faça o seguinte:
1. Verifique a mensagem retornada como parte do corpo de HttpResponse em busca de mensagens 404 comuns:
* *The requested service config is either invalid or not configured for sessions*. Verifique se o SCID que está sendo usado está correto.
* *The requested session wasn't found*. Verifique se a sessão foi criada e se o modelo de sessão está correto antes de recuperá-la. Você pode criar uma sessão com uma chamada PUT.
2. Verifique o URI que você está usando.
3. Reinicie o console e/ou tente novamente com um novo usuário.
### Estou recebendo um erro 403 ao chamar o MPSD.
Geralmente, isso é um problema de permissões ou de escopo.
Colete rastreamentos do Fiddler para obter mais informações e, em seguida, faça o seguinte:
1. Verifique as mensagens retornadas como parte do corpo de HttpResponse em busca de mensagens 403 comuns:
* \*The requested service config cannot be accessed. \*
* Verifique se você está usando uma conta que tem acesso à sandbox.
* Verifique se você está na sandbox correta.
* Se você estiver usando autenticação por certificado e receber esse erro, entre em contato com seu DAM.
* *The requested session cannot be accessed. Private Sessions can only be read by members of the session.*
* Você está tentando acessar uma sessão com visibilidade "private". Somente os membros da sessão podem ler o documento de sessão.
* *The request body can't contain existing member references unless the authentication principal includes a server.*
* Você não pode fazer outro usuário entrar em uma sessão em nome de um usuário. Você só pode convidar. Defina o índice como "`reserve_`" para convidar um jogador.
### Estou recebendo um erro 412 Precondition Failed.
Isto retornará 412 Precondition Failed se a sessão já existir:
```http theme={null}
> PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/foo HTTP/1.1
> Content-Type: application/json
> If-None-Match: \*
```
Isto retornará 412 Precondition Failed se o etag da sessão não corresponder ao cabeçalho If-Match:
```http theme={null}
> PUT /serviceconfigs/00000000-0000-0000-0000-000000000000/sessiontemplates/quick/sessions/foo HTTP/1.1
> Content-Type: application/json
> If--Match: 9555A7DE-8B91-40E4-8CFB-0629312C9C7D
```
### Estou recebendo erros como 405, 409, 503 e 400 ao chamar o MPSD.
Colete rastreamentos do Fiddler para obter mais informações e, em seguida, verifique as mensagens retornadas como parte do corpo de HttpResponse.
Você também pode obter o corpo da resposta se estiver usando as XSAPIs definindo a propriedade [HCSettingsSetTraceLevel](/pt-BR/reference/live/httpclient/trace/functions/hcsettingssettracelevel) como [HCTraceLevel](/pt-BR/reference/live/httpclient/trace/enums/hctracelevel)::Information, o que exibirá as informações na saída de depuração se [HCTraceSetTraceToDebugger](/pt-BR/reference/live/httpclient/trace/functions/hctracesettracetodebugger) estiver definido, ou você pode usar [HCTraceSetClientCallback](/pt-BR/reference/live/httpclient/trace/functions/hctracesetclientcallback) para obter um retorno de chamada no qual pode adicionar o log de rastreamento ao registro de rastreamento do seu próprio jogo. Você também pode usar [XblAddServiceCallRoutedHandler](/pt-BR/reference/live/xsapi-c/xbox_live_global_c/functions/xbladdservicecallroutedhandler) para ser chamado a cada chamada de serviço, que você pode encaminhar para seu próprio registro em log.
### O que posso ou devo alterar nos modelos do meu título?
Os modelos de sessão não são padrões, mas sim uma espécie de molde.
No entanto, você não pode substituir as constantes já definidas nos modelos, embora possa adicionar outras.
### Estou recebendo um erro informando que minha sessão não foi inicializada.
Quando a inicialização de membros está presente no seu modelo (geralmente em cenários de jogo, party e tíquete de partida), você precisa garantir que "initialize=true" esteja definido para reservas de membros suficientes (membros necessários para iniciar) para passar no QoS e corrigir esse problema.
### Minha sessão não está sendo criada e estou recebendo um erro HTTP 204.
Isso indica que nenhum usuário foi adicionado à sessão quando você a criou.
Se não houver usuários para uma sessão no momento da criação, a sessão não será criada.
Certifique-se de adicionar pelo menos um jogador a uma sessão na criação.
Em cenários de servidor dedicado, obtenha um jogador que esteja tentando criar uma partida, ou que precise criar uma partida, e torne esse usuário o jogador inicial dessa partida.
Como alternativa, você pode alterar ou remover o **sessionEmptyTimeout**.
### Quando devo sondar o MPSD?
Você deve evitar sondar as sessões do MPSD.
Em termos gerais, você pode fazer isso projetando seu código de forma que ele use a sessão do MPSD apenas para o estabelecimento inicial da conectividade de rede de cada cliente e para restabelecer o estado da rede de um ou mais clientes que perderam a conectividade.
Também é importante aproveitar os primitivos de sincronização baseados em etag do MPSD para eliminar a necessidade de atualizar o estado da sessão para resolver condições de corrida.
Uma aplicação comum desses princípios é quando você tem um conjunto de N clientes que precisam se conectar e jogar em uma malha ponto a ponto.
Em vez de consultar regularmente a sessão em busca de novos membros, cada membro pode entrar na sessão, conectar-se aos membros que já estão nela e presumir que todos os que entrarem depois farão o mesmo.
Veja os exemplos Chat e Player Rendezvous para conferir como implementar isso.
Há alguns casos raros em que a sondagem pode ser necessária por breves períodos; entre em contato com seu gerente de conta de desenvolvedor se achar que precisa fazer isso.
## Related topics
- [Introdução à chamada direta do serviço Multiplayer](/pt-BR/services/xbox-services/multiplayer/concepts/live-intro-calling-mp-directly.md)
- [Multiplayer Session Directory (MPSD)](/pt-BR/services/xbox-services/multiplayer/mpsd/live-mpsd-nav.md)
- [Visão geral do Multiplayer Session Directory](/pt-BR/services/xbox-services/multiplayer/mpsd/live-mpsd-overview.md)
- [Conceitos do Multiplayer Session Directory (MPSD)](/pt-BR/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-concepts-nav.md)
- [Código de exemplo do Multiplayer Session Directory (MPSD)](/pt-BR/services/xbox-services/multiplayer/mpsd/how-to/live-mpsd-howto-nav.md)