Tratamento de erros no CloudScript - XBOX Game Development Documentation

Este tutorial descreve como reconhecer e tratar erros nos seus manipuladores do CloudScript.

Identificação

A primeira etapa é identificar o erro. Embora todo erro não capturado seja registrado e fique disponível na resposta ao chamador (cliente), você pode capturar o erro antecipadamente usando um bloco try/catch. Considere o seguinte trecho do CloudScript, que produz e captura o erro.

"use strict";

handlers.GenerateError = () => {
    try {
        server.GetPlayerStatistics({
            PlayFabId : "non-existing-player-id"
        });
    } catch (ex) {
        let error = ex.apiErrorInfo.apiError.error; // In this case - "InvalidParams"
        let errorCode = ex.apiErrorInfo.apiError.errorCode; // In this case : 1000
    }
}

Observou como os códigos de erro foram extraídos no bloco catch? Consulte nossa documentação de códigos de erro de métodos da API global para obter uma lista completa de erros.

O código de erro, por si só, é suficiente para identificar o erro.

Registro em log

Qualquer erro não tratado é adicionado à resposta, permitindo que o cliente processe o problema. Ao mesmo tempo, ele cria uma entrada de erro do CloudScript e a adiciona às estatísticas totais disponíveis no seu painel do CloudScript.

Game Manager: painel do CloudScript mostrando um gráfico de erros de API

Para forçar o registro da exceção na forma de uma cadeia de caracteres JSON, use o registro de erros por meio do objeto log.

"use strict";

handlers.GenerateError = () => {
    try {
        server.GetPlayerStatistics({
            PlayFabId : "non-existing-player-id"
        });
    } catch (ex) {
        log.error(ex);
    }
}

Por fim, você pode gravar eventos de título/jogador para processamento posterior por meio de análises.

"use strict";

handlers.GenerateError = () => {
    try {
        server.GetPlayerStatistics({
            PlayFabId : "non-existing-player-id"
        });
    } catch (ex) {
        server.WriteTitleEvent({
            EventName : 'cs_error',
            Body : ex
        });
    }
}

Recuperação

Nem sempre é possível se recuperar de erros. Problemas como InvalidArguments não deixam outra opção a não ser relatar o problema ao jogador. Há um subconjunto de erros em que uma estratégia de repetição pode ser aplicada. Os tipos de erro que podem ser repetidos estão descritos em Códigos de erro de métodos da API global. Pedimos que você garanta que atende aos seguintes requisitos ao aplicar uma estratégia de repetição:

A cada nova tentativa, o atraso entre as tentativas deve aumentar exponencialmente. Isso aumenta suas chances de uma chamada bem-sucedida e impede que seu jogo sobrecarregue o servidor do PlayFab (o que resultará em mais chamadas rejeitadas).
Você deve aplicar essa estratégia de repetição de forma seletiva, usando-a apenas para os códigos que valem a pena repetir.

Erro de tempo limite do CloudScript

O tempo de execução das chamadas de API do CloudScript é limitado a 4 segundos. Se o tempo de execução exceder 4 segundos, um InternalServerError será gerado, e o evento do PlayStream gravará um objeto Logs semelhante ao seguinte:

    "Logs":[
        {
        "Level":"Error",
        "Message":"PlayFab API request failure",
        "Data":{
            "request":{
                "PlayFabId":"9437A5ADDAE3012D"
            },
            "error":"Timeout",
            "api":"/Server/GetPlayerSegments"
        }
        }
    ]

Se você encontrar esse erro, poderá:

dividir seu CloudScript em segmentos de código menores, que serão executados em menos de 4 segundos.
mudar para o CloudScript usando Azure Functions, que, em alguns casos, tem limites de tempo limite maiores. Você pode ver os limites no guia de início rápido.

​Identificação

​Registro em log

​Recuperação

​Erro de tempo limite do CloudScript

Identificação

Registro em log

Recuperação

Erro de tempo limite do CloudScript