> ## 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.

# Convites do PlayFab Party e o modelo de segurança

> Visão geral conceitual de como os convites do PlayFab Party autorizam os jogadores a ingressar em uma rede e como o modelo de segurança controla o acesso ao chat e aos dados.

O PlayFab Party foi projetado para fornecer um ambiente de comunicação seguro por padrão. Isso ajuda a proteger jogos e jogadores, mas as restrições de segurança podem gerar dúvidas sobre o uso da API para os desenvolvedores. Esta página apresenta os recursos de segurança do PlayFab Party, concentrando-se principalmente nos convites e em padrões eficazes para usá-los.

O PlayFab Party usa criptografia e autenticação padrão do setor para toda a comunicação (dados de gerenciamento, dados do jogo e comunicação em tempo real). Isso inclui todas as transmissões ponto a ponto e todas as transações com os serviços do Azure, sejam eles serviços Web (que usam HTTPS) ou o serviço transparente de retransmissão na nuvem (que usa DTLS).

Limitar o acesso a uma rede é uma parte essencial da proteção da integridade da rede. Quatro coisas são necessárias para ingressar em uma rede:

* Conhecimento do [descritor de rede](/pt-BR/services/playfab/multiplayer/networking/concepts-objects#rede)
* Posse de um [token de entidade](/pt-BR/services/playfab/live-service-management/game-configuration/entities) `title_player_account` válido do PlayFab
* Conhecimento de um [identificador](#identificadores) de convite
* Presença da [ID de entidade](/pt-BR/services/playfab/live-service-management/game-configuration/entities) do PlayFab correspondente ao token no convite especificado, ou o convite especificado ser um [convite aberto](#usuários-e-convites-abertos)

Uma determinada rede do PlayFab Party pode ter no máximo [128 jogadores](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/multiplayer-server/request-party-service#partynetworkconfiguration).

## Convites

Um convite (`PartyInvitation`) é um objeto dentro de uma rede que concede ao usuário acesso à rede. Os convites podem ser [criados](#criação) e [revogados](#revogação) durante todo o tempo de vida de uma rede. Um convite tem um [criador](#criação), um [identificador](#identificadores) exclusivo, uma [configuração de revogabilidade](#convite-inicial-e-outros-convites) e um [conjunto de usuários](#usuários-e-convites-abertos) opcional especificado como IDs de entidade. Uma rede pode ter qualquer número de convites ativos, inclusive nenhum. Uma rede é sempre criada com um convite inicial.

## Tempo de vida do convite

Um convite fica ativo desde o momento em que é criado até ser revogado.

### Criação

Há duas maneiras de criar um convite. A primeira é chamando `PartyManager::CreateNewNetwork()`. Como um convite é necessário para ingressar em uma rede, um convite deve existir quando uma rede é criada. Esse convite é conhecido como convite inicial e tem algumas propriedades especiais [descritas abaixo](#convite-inicial-e-outros-convites). A segunda maneira é chamando `PartyNetwork::CreateInvitation()`.

O criador de um convite é o usuário especificado ao chamar `PartyNetwork::CreateInvitation()`. O convite inicial não tem criador.

Quando um convite é criado (ou ao ingressar em uma rede com um convite inicial ativo), um `PartyInvitationCreatedStateChange` é gerado.

<Info>
  O convite inicial não permite implicitamente que o criador de uma rede ingresse nela. A menos que um [convite aberto](#usuários-e-convites-abertos) esteja sendo usado, certifique-se de incluir a ID de entidade do criador na lista de usuários.
</Info>

### Enumeração

A enumeração dos convites ativos é feita usando `PartyNetwork::GetInvitations()`. Somente os convites criados no dispositivo local, junto com o convite inicial, se ele ainda estiver ativo, podem ser enumerados.

### Revogação

Um convite é revogado chamando `PartyNetwork::RevokeInvitation()`. Somente o criador de um convite pode revogá-lo, exceto no caso do convite inicial, que pode ser revogado por qualquer usuário. Além disso, um convite é revogado automaticamente quando o usuário que o criou é removido da rede.

Quando um convite é revogado, um `PartyInvitationRevokedStateChange` é gerado em todos os dispositivos que podiam ver o convite.

Depois que o convite inicial é revogado, ele não pode ser criado novamente. Seu identificador pode ser reutilizado para um novo convite, mas esse novo convite não terá as propriedades especiais do convite inicial.

<Info>
  Revogar um convite não tem efeito sobre os dispositivos e usuários que já ingressaram na rede. Para remover um usuário ou dispositivo da rede, use `PartyNetwork::KickUser()` ou `PartyNetwork::KickDevice()`. Observe que esses métodos ainda não foram implementados.
</Info>

## Configuração do convite

A configuração de um convite é especificada durante a criação usando a struct `PartyInvitationConfiguration`.

### Identificadores

Cada convite tem um identificador que o identifica de forma exclusiva dentro da rede. Se um identificador não for especificado ao criar um convite, o Party atribuirá um. Para chamadas a `PartyManager::CreateNewNetwork()`, o identificador atribuído é retornado em um parâmetro de saída e também relatado em `PartyCreateNewNetworkCompletedStateChange` quando a criação da rede é concluída. Para chamadas a `PartyManager::CreateInvitation()`, o identificador atribuído pode ser recuperado do parâmetro de saída `invitation` ou do campo `invitation` em `PartyCreateInvitationCompletedStateChange` quando a criação do convite é concluída.

Embora o identificador de um convite deva ser exclusivo, depois que um convite é revogado, seu identificador pode ser reutilizado ao criar um novo convite.

### Convite inicial e outros convites

Embora haja apenas um tipo de convite, o convite inicial criado pela chamada a `PartyManager::CreateNewNetwork()` é um pouco diferente dos convites criados posteriormente por meio de `PartyNetwork::CreateInvitation()`. As diferenças estão resumidas na tabela abaixo.

| Propriedade | Convite inicial | Outros convites |
| - | - | - |
| Visibilidade | Todos os dispositivos podem ver o convite inicial. Enquanto o convite inicial não tiver sido revogado, as chamadas a `PartyNetwork::GetInvitations()` retornarão o convite inicial. Ao ingressar em uma rede, cada dispositivo recebe um `PartyInvitationCreatedStateChange` para o convite inicial, se ele não tiver sido revogado anteriormente. | Somente o dispositivo que criou o convite pode vê-lo. Um convite não inicial só é retornado por `PartyNetwork::GetInvitations()` se tiver sido criado naquele dispositivo, e um `PartyInvitationCreatedStateChange` só é gerado para ele no dispositivo criador. |
| Revogabilidade | Qualquer pessoa pode revogar o convite inicial. Ao especificar explicitamente a configuração do convite, a revogabilidade deve ser definida como `PartyInvitationRevocability::Anyone`. | Somente o criador pode revogar o convite. Ao criar o convite, a revogabilidade deve ser definida como `PartyInvitationRevocability::Creator`. |
| Tempo de vida | O convite inicial fica ativo até ser revogado explicitamente. | Um convite não inicial fica ativo até ser revogado explicitamente ou até que o usuário que o criou seja removido da rede. Quando o usuário é removido da rede, todos os convites que ele criou são revogados automaticamente. |
| Criador | O convite inicial não tem criador. `PartyInvitation::GetCreatorEntityId()` retorna nulo. | O usuário especificado ao chamar `PartyNetwork::CreateInvitation` é o criador. `PartyInvitation::GetCreatorEntityId()` retorna a ID de entidade desse usuário. |

Os convites (exceto o convite inicial) ficam ocultos para os outros dispositivos por motivos de privacidade. Confira o [padrão de uso de lista de amigos](#lista-de-amigos) para ver um exemplo de por que isso é importante.

### Usuários e convites abertos

Um convite contém 0 ou mais usuários especificados como [IDs de entidade](/pt-BR/services/playfab/live-service-management/game-configuration/entities) `title_player_account`. Se um convite contiver usuários, ele concederá acesso para ingressar na rede apenas a esses usuários. No entanto, se um convite não contiver usuários, ele será um convite aberto. Qualquer usuário pode ingressar na rede com o identificador de um convite aberto.

<Note>
  Em um dispositivo multiusuário, como um console de jogos, certifique-se de usar o convite correto com o usuário correto. Dependendo de quais usuários estão especificados em cada convite, é possível que usuários diferentes no dispositivo precisem usar convites diferentes ao autenticar um usuário na rede por meio de PartyNetwork::AuthenticateLocalUser().
</Note>

### Imutabilidade

Depois que um convite é criado, sua configuração não pode ser alterada. No entanto, depois que um convite é revogado, outro pode ser criado com o mesmo identificador, mas com uma configuração diferente. Confira o [padrão de uso de convite único dinâmico](#convite-único-dinâmico).

## Padrões de uso

Os convites do PlayFab Party são simples, mas flexíveis. Há muitas maneiras eficazes de usá-los para obter diferentes modelos de acesso a uma rede.

### Rede aberta

Uma rede aberta é a mais simples de entender e implementar. Ela permite que qualquer pessoa com o descritor de rede e o identificador do convite ingresse.

Crie uma rede aberta passando nulo para o parâmetro `initialInvitationConfiguration` ao chamar `PartyManager::CreateNewNetwork()`. O identificador do convite aberto é retornado como um parâmetro de saída. Depois que a criação da rede for concluída, compartilhe o descritor de rede e o identificador do convite para permitir que os usuários ingressem.

Opcionalmente, você pode fechar a rede a qualquer momento no futuro revogando o convite inicial.

<Warning>
  Como uma rede é tão segura quanto os dispositivos e usuários que ingressam nela, tenha cuidado ao compartilhar o descritor de rede e o identificador do convite de uma rede aberta.
</Warning>

### Lista de usuários estática

Para jogos que conhecem todos os jogadores com antecedência, como um jogo criado por matchmaking sem preenchimento, uma lista de usuários estática é um padrão fácil e eficaz. Isso permite que apenas os usuários identificados antes do início do jogo ingressem na rede.

Crie uma struct `PartyInvitationConfiguration` e adicione os usuários conhecidos ao campo `entityIds` dela. Passe essa struct para `PartyManager::CreateNewNetwork()`. Depois que a criação da rede for concluída, compartilhe o descritor de rede e o identificador do convite para permitir que os usuários ingressem.

### Convites individuais

Em um jogo em que os usuários existentes convidam outros usuários individualmente, um padrão de convites individuais é eficaz e simples.

Crie uma struct `PartyInvitationConfiguration` e adicione apenas o criador ao campo `entityIds` dela. Passe essa struct para `PartyManager::CreateNewNetwork()`. Depois que o criador se conectar à rede, o convite inicial poderá ser revogado, opcionalmente. Como alternativa, o criador da rede pode criar uma [rede aberta](#rede-aberta) e, em seguida, revogar o convite inicial assim que se conectar.

Crie outra struct `PartyInvitationConfiguration` para cada usuário que deve ingressar na rede. Crie convites passando essas structs para `PartyNetwork::CreateInvitation()`. Compartilhe o descritor de rede com cada usuário, junto com o identificador do convite específico dele. À medida que os usuários ingressam, eles podem repetir esse padrão para convidar mais usuários.

Depois que um usuário ingressar, o convite específico dele poderá ser revogado, opcionalmente.

### Lista de amigos

Para jogos que desejam permitir que os amigos de cada usuário ingressem facilmente sem criar [convites individuais](#convites-individuais), é possível criar convites que contenham as listas de amigos completas dos usuários.

Depois de se conectar à rede, cada usuário criará uma struct `PartyInvitationConfiguration` e adicionará cada um dos seus amigos da plataforma social ao campo `entityIds` dela. Passe essa struct para `PartyNetwork::CreateInvitation()` e compartilhe o descritor de rede e o identificador do convite com os amigos. Quando a lista de amigos de um usuário mudar, o convite deverá ser revogado e um novo convite deverá ser criado com a nova lista de amigos.

### Convite único dinâmico

Muitos jogos têm um lobby ou outro serviço externo que controla quem deve ingressar em uma determinada rede. Para manter uma rede sincronizada com o serviço externo, um padrão de convite único dinâmico pode ser usado. Esse padrão usa um único convite com um identificador conhecido.

Há duas variantes desse padrão. O serviço externo pode selecionar um único usuário para gerenciar os convites da rede ou pode pedir que todos os usuários tentem gerenciar os convites. Em ambos os casos, sempre que o conjunto de usuários que deve estar na rede muda, o serviço externo notifica os usuários, e os usuários tentam revogar o convite atual e criar um novo convite com o mesmo identificador conhecido contendo o novo conjunto completo de usuários.

#### Gerenciamento por um único usuário

Ter um único usuário responsável por revogar o convite atual e criar o novo convite leva a uma propriedade previsível do convite. No entanto, o serviço externo precisa fazer o seguinte.

* Selecionar o usuário que gerenciará os convites.
* Selecionar um novo usuário quando o usuário anterior sair da rede.

#### Gerenciamento por todos os usuários

Fazer com que todos os usuários tentem gerenciar os convites leva a uma propriedade imprevisível do convite, mas evita que o serviço externo precise selecionar um único usuário. Em vez disso, um usuário em cada dispositivo faz o seguinte.

* Tenta revogar o convite atual. No caso do convite inicial, todos os usuários tentam fazer isso, mas apenas um terá êxito. No caso de outros convites, somente o usuário que criou o último convite pode tentar revogá-lo, pois o convite não fica visível para os outros usuários.
* Tenta criar um novo convite. Como os convites devem ter identificadores exclusivos, apenas um dos usuários terá êxito. Esse usuário deve notificar os outros de que é o novo proprietário do convite, pois o convite não fica visível em outros dispositivos.
* Quando o criador do convite atual sai do dispositivo criador, todos os usuários devem tentar novamente criar um novo convite.

<Info>
  Ao revogar um convite e criar um novo com o mesmo identificador, há uma pequena janela de tempo em que o identificador do convite é inválido. Se você estiver usando essa abordagem, será necessário repetir a chamada a `PartyNetwork::AuthenticateLocalUser()` caso ela falhe, após um período de espera razoável.
</Info>

### Convite aberto rotativo

Para jogos em que um lobby ou outro serviço externo controla quem deve ingressar em uma determinada rede, uma alternativa ao padrão de [convite único dinâmico](#convite-único-dinâmico) é o padrão de convite aberto rotativo. Nesse padrão, há sempre um único convite aberto. O convite é revogado e recriado com um novo identificador sempre que um usuário que antes tinha permissão para ingressar é removido da lista de usuários do serviço externo. O identificador do convite funciona como uma senha e deve ser protegido da mesma forma. O padrão pode ser implementado nestas etapas:

* O serviço externo seleciona um dispositivo para criar a rede e especifica o identificador de convite a ser usado.
* O serviço externo envia o identificador do convite para todos os outros usuários que devem ingressar na rede.
* Quando um novo usuário deve ingressar na rede, o serviço externo compartilha o identificador do convite atual com esse usuário.
* Quando um usuário que tem o convite atual não deve mais ter permissão para ingressar, o serviço externo precisa "alterar a senha" fazendo o seguinte.
  * Selecionar um novo identificador de convite.
  * Solicitar que um ou todos os usuários revoguem o convite atual e criem um novo com o identificador de convite selecionado. Confira [convite único dinâmico](#convite-único-dinâmico) para ver uma discussão sobre o gerenciamento por um único usuário em comparação com o gerenciamento por todos os usuários.
  * Compartilhar o novo identificador de convite com todos os usuários que agora devem ter permissão para ingressar na rede.

## Próximas etapas

* [Saiba como o PlayFab Party interage com seus fluxos de descoberta](/pt-BR/services/playfab/multiplayer/networking/concepts-discovery)


## Related topics

- [Objetos do PlayFab Party e suas relações](/pt-BR/services/playfab/multiplayer/networking/concepts-objects.md)
- [Redes do PlayFab Party e fluxos de descoberta de rede](/pt-BR/services/playfab/multiplayer/networking/concepts-discovery.md)
- [Referência do modelo de eventos do PlayStream para o PlayFab](/pt-BR/services/playfab/api-references/events/index.md)
- [Notas de versão do PlayFab Party XBOX Live Helper](/pt-BR/services/playfab/multiplayer/networking/party-xboxlive-relnotes.md)
- [Requisitos do XBOX](/pt-BR/services/playfab/multiplayer/networking/xbox-requirements.md)