> ## 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.
# Usando tíquetes de preenchimento de servidor - API REST
> Crie e gerencie tíquetes de preenchimento do PlayFab Matchmaking por meio da API REST para adicionar jogadores a partidas já em andamento e manter os servidores de jogo cheios.
É altamente recomendável considerar o uso dos Multiplayer SDKs, pois eles incluem suporte a mensagens em tempo real que reduz a necessidade de sondagem, melhorando a experiência de matchmaking e reduzindo atrasos. [Usando tíquetes de preenchimento de servidor - Multiplayer SDK](/pt-BR/services/playfab/multiplayer/matchmaking/backfill-tickets-multiplayer-sdk)
Jogos hospedados em um servidor às vezes precisam procurar jogadores
adicionais. Na maioria das vezes, isso ocorre quando um ou mais jogadores se desconectam enquanto o
jogo está em andamento. Os tíquetes de preenchimento de servidor permitem que um servidor de jogo procure
jogadores adicionais que se encaixem no jogo que está sendo jogado no momento.
Os tíquetes de preenchimento de servidor diferem dos tíquetes de matchmaking comuns de várias maneiras:
1. Correspondência
* Tíquetes de preenchimento não podem ser combinados entre si.
* Tíquetes de preenchimento recebem prioridade durante a pesquisa. Isso reduz a
fragmentação da base de jogadores.
2. Contrato
* Tíquetes de preenchimento podem ser criados com um campo `ServerDetails`. Isso permite
que o servidor indique como os jogadores combinados devem se conectar a ele.
* Tíquetes de preenchimento podem ser criados com atribuições de equipe. Isso permite que jogos
com equipes mantenham as informações de suas equipes.
3. Propriedades da fila
* Tíquetes de preenchimento não disparam a [alocação de Multiplayer Server](/pt-BR/services/playfab/multiplayer/matchmaking/multiplayer-servers).
* Tíquetes de preenchimento não são refletidos nas [estatísticas da fila](/pt-BR/services/playfab/multiplayer/matchmaking/display-statistics), pois seus jogadores
já estão jogando uma partida e distorceriam o tempo de espera de forma imprecisa.
4. Propriedade
* Tíquetes de preenchimento pertencem a um servidor de jogo, não a um usuário. Os usuários não podem
visualizar nem interagir com tíquetes de preenchimento de forma alguma.
## Criando um tíquete de preenchimento de servidor
O processo de preenchimento começa de forma semelhante à criação de um tíquete de matchmaking comum,
mas com a chamada
[CreateServerBackfillTicket](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/create-server-backfill-ticket)
em vez de uma chamada
[CreateServerMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.createservermatchmakingticket).
O servidor de jogo deve fornecer todas as informações de membros do jogo que está
hospedando no momento. A maneira mais eficiente de fazer isso é armazenar os atributos
retornados no resultado da partida anterior. Esses atributos podem ser recuperados
chamando
[GetMatch](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch)
com o sinalizador `ReturnMemberAttributes`. Como alternativa, o servidor de jogo pode consultar
os usuários para obter as informações de atributos.
Além dos membros, o servidor de jogo pode especificar duas informações
adicionais.
### ServerDetails
Essa estrutura é idêntica à estrutura retornada em uma chamada
[GetMatch](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch)
e permite que o servidor especifique quaisquer informações necessárias para se conectar a ele. Quando
o tíquete de preenchimento é combinado, sua estrutura
[ServerDetails](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch#serverdetails)
é retornada a todos os jogadores que chamarem
[GetMatch](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch) na
partida resultante. Todos os campos dessa estrutura são opcionais. Os títulos podem precisar apenas
de um subconjunto deles para fornecer informações suficientes para que os clientes
se conectem ao servidor de jogo.
O campo `IPV4Address` não é validado e pode ser usado para fornecer informações arbitrárias de cadeia de conexão aos clientes.
```json theme={null}
{
"ServerDetails": {
"IPV4Address": "123.234.123.234",
"Ports": [
{
"Port": {
"Name": "portname",
"Num": 12345,
"Protocol": "UDP"
}
}
],
"Region": "EastUS"
}
}
```
### Atribuições de equipe
Se o tíquete de preenchimento for enviado a uma fila com equipes, cada membro também poderá
ser especificado com um TeamId, indicando a equipe em que está no momento. Essa
associação é preservada quando uma partida é retornada. Se um TeamId não for
especificado para um usuário, ele poderá ser colocado em qualquer equipe.
```json theme={null}
{
"Members": [
{
"TeamId": "red",
"Entity": {
"Id": "6570DE3537DC9DF6",
"Type": "title_player_account",
"TypeString": "title_player_account"
},
"Attributes": {
"DataObject": {
"Skill": 25
}
}
}
]
}
```
## Interagindo com um tíquete de preenchimento
Depois de criado, um tíquete de preenchimento começa a procurar tíquetes de matchmaking comuns
que atendam aos critérios das regras. O fluxo dos tíquetes de preenchimento é idêntico ao funcionamento
dos tíquetes de matchmaking comuns, exceto pelo uso de APIs análogas. O servidor de jogo
pode verificar o status do seu tíquete chamando [GetServerBackfillTicket](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/create-server-backfill-ticket).
Ele também pode cancelar o tíquete chamando [CancelServerBackfillTicket](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/cancel-server-backfill-ticket?view=playfab-rest).
Os clientes não têm permissão para cancelar um tíquete de preenchimento do qual fazem parte. Suponha que um cliente esteja em uma partida 4v4 e que um jogador da equipe adversária tenha saído. O cliente poderia manter sua vantagem cancelando continuamente todos os tíquetes de preenchimento dos quais fizesse parte. Para evitar isso, somente servidores de jogo podem cancelar tíquetes de preenchimento.
## Limites de associação e recuperação de tíquetes de preenchimento perdidos
Assim como nos tíquetes de matchmaking comuns, um usuário pode estar em apenas um
tíquete de preenchimento por fila a qualquer momento. Esse limite é controlado separadamente dos tíquetes
comuns que um cliente controla.
Caso um servidor de jogo crie um tíquete de preenchimento e depois falhe, todos os
usuários do tíquete de preenchimento perdido não poderão ser enviados em outro
tíquete de preenchimento devido ao limite de associação. Um servidor de jogo descobre isso
ao receber o erro `MatchmakingTicketMembershipLimitExceeded`, junto com uma
lista de usuários que indica quais têm tíquetes de preenchimento pendentes em um
corpo `errorDetails`.
```json theme={null}
{
"code": 400,
"status": "BadRequest",
"error": "MatchmakingTicketMembershipLimitExceeded",
"errorCode": 2055,
"errorMessage": "User is a member of too many backfill tickets.",
"errorDetails": {
"UsersExceedingMembershipLimit": [
"title_player_account!562D72A5B184F612"
]
}
}
```
O servidor de jogo pode recuperar um usuário dessa situação chamando
[CancelAllServerBackfillTicketsForPlayer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/cancel-all-server-backfill-tickets-for-player),
que remove todos os tíquetes de preenchimento dos quais o usuário faz parte.
[ListServerBackfillTicketsForPlayer](https://learn.microsoft.com/en-us/rest/api/playfab/multiplayer/matchmaking/list-server-backfill-tickets-for-player)
também é fornecido como um método para descobrir em quais tíquetes de preenchimento um jogador pode
estar.
## Interações com a regra de seleção de região
A regra de seleção de região normalmente exige que os tíquetes especifiquem uma matriz de
medições de latência para o seu atributo. Um tíquete de preenchimento, no entanto, representa
um jogo já em andamento em um datacenter específico. Em vez de uma matriz de
medições de latência, a solicitação criada deve especificar uma região na estrutura
[ServerDetails](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatch#serverdetails).
Para que os tíquetes sejam combinados com o tíquete de preenchimento, eles devem ter um
tempo de ping aceitável para a região especificada pelo tíquete de preenchimento.
## Interações com a regra de similaridade de tamanho de tíquete de equipe
A regra de similaridade de tamanho de tíquete de equipe garante que grandes grupos de jogadores sejam
combinados com outros grandes grupos de jogadores. No entanto, os tíquetes de preenchimento não
contêm a informação de quais jogadores entraram no jogo como um grupo. Por isso,
a regra de similaridade de tamanho de tíquete é ignorada ao combinar tíquetes de preenchimento.
## Related topics
- [Usando tíquetes de preenchimento de servidor - Multiplayer SDK](/pt-BR/services/playfab/multiplayer/matchmaking/backfill-tickets-multiplayer-sdk.md)
- [Obter tíquete de preenchimento do servidor](/pt-BR/services/playfab/api-references/rest/multiplayer/matchmaking/get-server-backfill-ticket.md)
- [Cancelar tíquete de preenchimento do servidor](/pt-BR/services/playfab/api-references/rest/multiplayer/matchmaking/cancel-server-backfill-ticket.md)
- [Criar tíquete de preenchimento do servidor](/pt-BR/services/playfab/api-references/rest/multiplayer/matchmaking/create-server-backfill-ticket.md)
- [Listar tíquetes de preenchimento do servidor do jogador](/pt-BR/services/playfab/api-references/rest/multiplayer/matchmaking/list-server-backfill-tickets-for-player.md)