Práticas recomendadas para chamar os serviços do XBOX - XBOX Game Development Documentation

Os serviços do XBOX podem ser chamados de duas maneiras principais: usando a XBOX Services API (XSAPI) ou chamando diretamente os pontos de extremidade REST. Independentemente de como seu código chama os serviços do XBOX, é importante ter padrões de chamada e lógica de repetição adequados. Para entender como escrever uma lógica de repetição adequada, é necessário conhecer os dois tipos de pontos de extremidade REST: idempotentes e não idempotentes. Eles são descritos abaixo.

Pontos de extremidade não idempotentes

Os métodos HTTP que têm efeitos colaterais quando chamados repetidamente são considerados não idempotentes. Isso significa que, se um cliente chamar o ponto de extremidade e ocorrer um tempo limite de rede, não será seguro repetir o método, porque o recurso pode ter sido atualizado sem que a rede conseguisse notificar o chamador de que a operação foi bem-sucedida. Em caso de erro, em vez de repetir, o cliente precisa primeiro consultar se a chamada foi bem-sucedida. Somente se a chamada não tiver sido bem-sucedida ele deverá repeti-la. Na XBOX Services API, algumas APIs são marcadas internamente como chamadoras de pontos de extremidade não idempotentes. Isso significa que, se ocorrerem falhas ao chamar esses pontos de extremidade, as APIs não repetirão automaticamente a chamada ao ponto de extremidade. A lista completa de APIs não idempotentes é:

Métodos idempotentes

Os métodos HTTP idempotentes, por outro lado, não deixam efeitos colaterais. Isso, por sua vez, significa que é seguro repeti-los. Na XBOX Services API, todos os métodos idempotentes são repetidos automaticamente sob determinadas condições. A lista completa de APIs idempotentes inclui todas as APIs que não foram listadas acima como não idempotentes.

Práticas recomendadas de lógica de repetição

Para chamadas idempotentes, estas condições devem ser repetidas automaticamente:

Todos os erros de rede
401: Unauthorized
408: RequestTimeout
429: Too Many Requests
500: InternalError
502: BadGateway
503: ServiceUnavailable
504: GatewayTimeout

Na UWP, o 401: Unauthorized recebe um tratamento especial. Esse valor indica que o token de autenticação dos serviços do XBOX expirou; por isso, a XBOX Services API chama o SO para atualizar o token e, em seguida, executa uma única repetição. Quando uma repetição é executada, a prática recomendada é não chamar o serviço até que o tempo do cabeçalho “Retry-After” seja atingido. A XSAPI agora implementa essa prática recomendada. Se um código de status HTTP de falha e um cabeçalho “Retry-After” forem retornados para qualquer API, chamadas adicionais a essa mesma API antes do tempo de Retry-After retornarão imediatamente com o erro original, sem acessar o serviço. Ao repetir uma chamada, a prática recomendada é usar uma retirada exponencial com uma variação aleatória (jitter) para distribuir a carga no serviço. A XSAPI começa com um atraso padrão de 2 segundos, controlado por XblContextSettingsSetHttpRetryDelay. Isso significa que, por padrão, cada repetição faz uma retirada exponencial de 2, 4, 8 ou mais segundos. Ela varia o atraso entre o valor de retirada atual e o próximo com base no tempo de resposta, para distribuir ainda mais a carga entre o conjunto de dispositivos que estão tentando repetir a chamada. Os títulos devem controlar quanto tempo gastar repetindo uma chamada. Usando a XSAPI, os desenvolvedores têm controle direto sobre isso por meio da função XblContextSettingsSetHttpTimeoutWindow. Por padrão, esse valor é definido como 20 segundos. Defini-lo como 0 segundos desativa efetivamente a lógica de repetição.

Ajuste dinâmico do tempo limite HTTP interno

A XSAPI ajusta dinamicamente o tempo limite HTTP interno com base no tempo restante em XblContextSettingsGetHttpTimeoutWindow. O tempo limite HTTP interno controla quanto tempo o SO gasta executando a operação de rede HTTP antes de abortá-la. A chamada não será repetida a menos que restem pelo menos 5 segundos em XblContextSettingsGetHttpTimeoutWindow, para dar tempo razoável para a chamada ser concluída. Essa regra não se aplica à primeira chamada; portanto, definir XblContextSettingsSetHttpTimeoutWindow como 0 é aceitável e resultará em uma única chamada. Essa lógica faz com que XblContextSettingsGetHttpTimeoutWindow seja mais determinística quanto ao momento em que a chamada à API retornará. Se um cabeçalho “Retry-After” for retornado, nenhuma repetição será feita até que o tempo de “Retry-After” seja atingido. Se o tempo de “Retry-After” for posterior a XblContextSettingsGetHttpTimeoutWindow, a chamada retornará ao final de XblContextSettingsGetHttpTimeoutWindow.

Tratamento de erros

Os desenvolvedores de títulos devem sempre usar o tratamento de erros adequado para todas as chamadas de serviço; eles precisam garantir que estão tratando corretamente as respostas de falha. Há muitas condições do mundo real que podem fazer com que uma requisição aos serviços do XBOX retorne códigos de falha, como:

A rede não está disponível. Por exemplo, o dispositivo perdeu o 4G, perdeu o Wi-Fi ou a rede caiu.
Carga excessiva nos serviços (503).
Ocorreu uma falha no serviço (500).
Foram enviadas requisições demais ao serviço (429).
Conflito de operação de gravação (412). Por exemplo, outro jogador em uma sessão multiplayer enviou uma alteração primeiro.
O usuário foi banido ou não tem permissão.
O usuário saiu.

O tratamento de erros adequado é fundamental para garantir que o jogo funcione corretamente nessas condições. Para obter detalhes sobre as práticas recomendadas de tratamento de erros, consulte Tratamento de erros. Para ver um vídeo que aborda esse tema, consulte a palestra XSAPI: C++, No Exceptions! em Xfest 2015 Videos.

Melhores padrões de chamada

Use requisições em lote

Alguns pontos de extremidade oferecem suporte ao envio em lote ou à agregação de um conjunto de requisições em uma única chamada. Por exemplo, com o serviço de perfil dos serviços do XBOX, você pode solicitar o perfil de um único usuário ou os perfis de um conjunto de usuários. Portanto, se você precisar dos perfis de um conjunto de usuários, seria muito ineficiente chamar o ponto de extremidade ou a API um de cada vez para cada perfil de usuário. Cada chamada adiciona muita sobrecarga de autenticação. Em vez disso, passe todos os usuários sobre os quais você deseja informações de uma só vez para a API, para que o ponto de extremidade possa processar todos os perfis de usuário ao mesmo tempo e retornar uma única resposta.

Use o serviço Real-Time Activity (RTA) em vez de sondagem

Uma prática recomendada é usar o serviço Real-Time Activity (RTA) em vez de sondagens periódicas. O serviço Real-Time Activity expõe um web socket que envia uma notificação aos clientes quando os recursos de destino mudam no serviço. O serviço RTA envia notificações sobre alterações de presença, alterações de estatísticas, alterações em documentos de sessão multiplayer e alterações de relacionamentos sociais. Para saber em quais informações o cliente está interessado, o cliente precisa primeiro assinar o item pelo web socket. Isso evita sondar o serviço para detectar alterações, pois você será informado exatamente quando o item mudar. A XSAPI expõe o serviço RTA como um conjunto de APIs de assinatura que os clientes podem usar. Cada uma dessas APIs tem APIs *ChangedHandler correspondentes, que recebem uma função de callback que será chamada quando um item mudar.

XblPresenceSubscribeToDevicePresenceChange
XblPresenceSubscribeToTitlePresenceChange
XblUserStatisticsSubscribeToStatisticChange
XblSocialSubscribeToSocialRelationshipChange

Use os gerenciadores do lado do cliente da XSAPI

A XSAPI tem um conjunto de gerenciadores que atuam como cache e máquinas de estado e que fazem todo o trabalho pesado em determinados cenários. O Social Manager faz todo o trabalho pesado relacionado às listas de amigos e aos perfis. O Social Manager mantém sua lista de amigos, os perfis deles e os dados de presença atualizados usando o serviço RTA. O Social Manager expõe uma API síncrona muito amigável para mecanismos de jogo. Os jogos podem chamar as APIs do Social Manager com frequência, porque o Social Manager mantém um cache em memória das informações mais recentes do serviço. Consulte Social Manager.

Multiplayer Manager

Para o gerenciamento de sessões multiplayer, o Multiplayer Manager é uma solução pronta para jogos multiplayer tradicionais. A API do Multiplayer Manager inclui gerenciamento de lista de jogadores e de sessões, trata convites de jogo, entrada em partidas em andamento e matchmaking e se conecta à sua solução de rede existente. Ela faz todo o trabalho pesado relacionado à implementação de fluxos multiplayer tradicionais. Consulte Multiplayer Manager.

Limitação (limitação de taxa refinada)

Os serviços do XBOX têm limitação de taxa para impedir que um único dispositivo coloque uma carga extrema no serviço. É importante saber quando seu título foi limitado. Para determinar se o seu título foi limitado, use qualquer uma destas abordagens:

Monitorar o código de status HTTP 429
Usar asserções de depuração
Usar a ferramenta Trace Analyzer dos serviços do XBOX

Essas abordagens são descritas abaixo.

Monitorando o código de status HTTP 429

Você pode usar o Fiddler e observar se um código de status HTTP 429 é retornado. A resposta JSON conterá detalhes sobre como o ponto de extremidade foi limitado. Por exemplo:

{
  "version":1,
  "currentRequests":13,
  "maxRequests":10,
  "periodInSeconds":120,
  "limitType":"Rate"
}

Se você estiver usando a XSAPI, as APIs retornarão um erro HTTP_E_STATUS_429_TOO_MANY_REQUESTS e definirão a mensagem de erro para mostrar detalhes sobre como a API foi limitada.

Usando asserções de depuração

Ao usar a XSAPI, se a chamada for limitada em uma área restrita de desenvolvedor e com um build de depuração do título, ocorrerá uma asserção para informar imediatamente ao desenvolvedor que houve uma limitação. Isso evita que um erro de limitação 429 passe despercebido devido a um código escrito incorretamente. Se você quiser desabilitar essas asserções para continuar trabalhando sem corrigir o código problemático, poderá usar a API XblDisableAssertsForXboxLiveThrottlingInDevSandboxes:

XblDisableAssertsForXboxLiveThrottlingInDevSandboxes(
    XblConfigSetting::ThisCodeNeedsToBeChanged
);

Observe que essa API não impedirá que seu título seja limitado. Seu título ainda será limitado. Ela simplesmente desabilita as asserções em áreas restritas de desenvolvimento ao usar um build de depuração.

Usando a ferramenta Trace Analyzer dos serviços do XBOX

Outra opção para determinar se o seu título foi limitado é gravar um rastreamento das chamadas aos serviços do XBOX e analisá-lo com a ferramenta Trace Analyzer dos serviços do XBOX. Para gravar um rastreamento, você pode usar o Fiddler para gravar um arquivo .SAZ ou usar o registro em log de rastreamento interno da XSAPI. Para obter mais informações sobre como ativar os rastreamentos na XSAPI, consulte o artigo do XBOX Trace Analyzer dos serviços do XBOX (XblTraceAnalyzer.exe). Depois que você tiver um rastreamento, a ferramenta Trace Analyzer dos serviços do XBOX avisará quando detectar chamadas limitadas.

Os serviços do XBOX estão funcionando?

Os serviços do XBOX são um conjunto de microsserviços que expõem recursos do XBOX, como perfil, amigos e presença, estatísticas, placares, conquistas, multiplayer e matchmaking. Não existe um único servidor ou ponto de extremidade que defina se os serviços do XBOX estão funcionando. Se um único servidor cair, os demais microsserviços dos serviços do XBOX são, em grande parte, independentes e devem continuar operacionais. Se um único serviço sofrer uma interrupção temporária, é importante saber se a chamada a esse serviço é essencial para o seu jogo. Tente oferecer uma experiência razoável enquanto houver problemas intermitentes de rede ou de serviço. Por exemplo, se o serviço de presença estiver retornando falha, essa chamada provavelmente não é essencial para o seu jogo. Portanto, simplesmente informe ao usuário a última presença conhecida, em vez de informar que a rede XBOX (também conhecida como XBOX Live) está fora do ar. Os serviços do XBOX seguem o modelo de consistência “consistência eventual”. Isso significa que, se nenhuma nova atualização for feita, todas as requisições para aquele recurso acabarão retornando o último valor atualizado. Isso significa que há um curto período em que as informações ficam desatualizadas enquanto os dados se propagam.

​Pontos de extremidade não idempotentes

​Métodos idempotentes

​Práticas recomendadas de lógica de repetição

​Ajuste dinâmico do tempo limite HTTP interno

​Tratamento de erros

​Melhores padrões de chamada

​Use requisições em lote

​Use o serviço Real-Time Activity (RTA) em vez de sondagem

​Use os gerenciadores do lado do cliente da XSAPI

​Social Manager

​Multiplayer Manager

​Limitação (limitação de taxa refinada)

​Monitorando o código de status HTTP 429

​Usando asserções de depuração

​Usando a ferramenta Trace Analyzer dos serviços do XBOX

​Os serviços do XBOX estão funcionando?