Azure Cosmos DB para cabeçalhos de resposta do servidor Gremlin

APLICA-SE A: Gremlin

Este artigo aborda cabeçalhos que o servidor Azure Cosmos DB para Gremlin retorna ao chamador após a execução da solicitação. Esses cabeçalhos são úteis para solucionar problemas de desempenho de solicitações, criar aplicativos que se integram nativamente ao serviço Azure Cosmos DB e simplificar o suporte ao cliente.

Tenha em mente que, dependendo desses cabeçalhos, você está limitando a portabilidade do seu aplicativo para outras implementações Gremlin. Em troca, você está ganhando uma integração mais estreita com o Azure Cosmos DB para Gremlin. Esses cabeçalhos não são um padrão TinkerPop.

Cabeçalhos

Cabeçalho	Type	Valor da amostra	Quando Incluído	Explicação
x-ms-request-charge	duplo	11.3243	Sucesso e Fracasso	Quantidade de coleta ou taxa de transferência do banco de dados consumida em unidades de solicitação (RU/s ou RUs) para uma mensagem de resposta parcial. Esse cabeçalho está presente em todas as continuações para solicitações que têm vários blocos. Ele reflete a carga de um pedaço de resposta específico. Somente para solicitações que consistem em um único bloco de resposta, esse cabeçalho corresponde ao custo total da travessia. No entanto, para a maioria das travessias complexas, este valor representa um custo parcial.
x-ms-total-request-charge	duplo	423.987	Sucesso e Fracasso	Quantidade de coleta ou taxa de transferência do banco de dados consumida em unidades de solicitação (RU/s ou RUs) para toda a solicitação. Esse cabeçalho está presente em todas as continuações para solicitações que têm vários blocos. Indica cobrança cumulativa desde o início da solicitação. O valor desse cabeçalho no último bloco indica a cobrança completa da solicitação.
x-ms-servidor-time-ms	duplo	13.75	Sucesso e Fracasso	Este cabeçalho é incluído para fins de solução de problemas de latência. Ele indica a quantidade de tempo, em milissegundos, que o servidor do Azure Cosmos DB para Gremlin levou para executar e produzir uma mensagem de resposta parcial. Usar o valor desse cabeçalho e compará-lo com os aplicativos de latência de solicitação geral pode calcular a sobrecarga de latência da rede.
x-ms-total-servidor-time-ms	duplo	130.512	Sucesso e Fracasso	Tempo total, em milissegundos, que o servidor Azure Cosmos DB para Gremlin levou para executar toda a travessia. Este cabeçalho é incluído em todas as respostas parciais. Representa o tempo de execução cumulativo desde o início do pedido. A última resposta indica o tempo total de execução. Este cabeçalho é útil para diferenciar entre cliente e servidor como uma fonte de latência. Você pode comparar o tempo de execução transversal no cliente com o valor desse cabeçalho.
x-ms-status-code	long	200	Sucesso e Fracasso	O cabeçalho indica o motivo interno para a conclusão ou encerramento da solicitação. O aplicativo é aconselhado a olhar para o valor deste cabeçalho e tomar medidas corretivas.
x-ms-substatus-código	long	1003	Apenas falha	O Azure Cosmos DB é um banco de dados multimodelo criado sobre a camada de armazenamento unificada. Este cabeçalho contém informações adicionais sobre o motivo da falha quando a falha ocorre em camadas inferiores da pilha de alta disponibilidade. O aplicativo é aconselhado a armazenar esse cabeçalho e usá-lo ao entrar em contato com o suporte ao cliente do Azure Cosmos DB. O valor desse cabeçalho é útil para o engenheiro do Azure Cosmos DB para solução rápida de problemas.
x-ms-retry-after-ms	string (TimeSpan)	"00:00:03.9500000"	Apenas falha	Este cabeçalho é uma representação de cadeia de caracteres de um tipo .NET TimeSpan . Esse valor só será incluído em solicitações com falha devido ao esgotamento da taxa de transferência provisionada. A candidatura deve voltar a apresentar a travessia após um período de tempo instruído.
x-ms-activity-id	corda (Guid)	"A9218E01-3A3A-4716-9636-5BD86B056613"	Sucesso e Fracasso	O cabeçalho contém um identificador exclusivo do lado do servidor de uma solicitação. A cada solicitação é atribuído um identificador exclusivo pelo servidor para fins de rastreamento. Os aplicativos devem registrar identificadores de atividade retornados pelo servidor para solicitações sobre as quais os clientes podem querer entrar em contato com o suporte ao cliente. A equipe de suporte do Azure Cosmos DB pode encontrar solicitações específicas por esses identificadores na telemetria de serviço do Azure Cosmos DB.

Códigos de status

Os códigos mais comuns retornados para x-ms-status-code o atributo status pelo servidor estão listados abaixo.

Status	Explicação
401	A mensagem "Unauthorized: Invalid credentials provided" de erro é retornada quando a senha de autenticação não corresponde à chave de conta do Azure Cosmos DB. Navegue até sua conta do Azure Cosmos DB para Gremlin no portal do Azure e confirme se a chave está correta.
404	Operações simultâneas que tentam excluir e atualizar a mesma borda ou vértice simultaneamente. A mensagem de erro "Owner resource does not exist" indica que a base de dados ou a coleção especificada está incorreta nos parâmetros de ligação no formato /dbs/<database name>/colls/<collection or graph name>.
409	"Conflicting request to resource has been attempted. Retry to avoid conflicts." normalmente, ocorre quando um vértice ou uma margem com um identificador já existe no gráfico.
412	O código de status é complementado com a mensagem "PreconditionFailedException": One of the specified pre-condition is not metde erro . Este erro é indicativo de uma violação de controle de simultaneidade otimista entre ler uma aresta ou vértice e gravá-lo de volta à loja após a modificação. As situações mais comuns em que esse erro ocorre é a modificação de propriedade, por exemplo g.V('identifier').property('name','value'). O motor Gremlin lia o vértice, modificava-o e escrevia-o de volta. Se houver outra travessia correndo em paralelo tentando escrever o mesmo vértice ou uma aresta, um deles receberá esse erro. O aplicativo deve enviar a travessia para o servidor novamente.
429	o pedido foi limitado e deve ser repetido após o valor em x-ms-repetição-após-ms
500	a mensagem de erro que contém "NotFoundException: Entity with the specified id does not exist in the system." indica que uma base de dados e/ou coleção foram recriadas com o mesmo nome. Este erro desaparecerá dentro de 5 minutos à medida que a alteração se propaga e invalida caches em diferentes componentes do Azure Cosmos DB. Para evitar este problema, utilize sempre nomes de bases de dados e coleções exclusivos.
1000	Esse código de status é retornado quando o servidor analisou uma mensagem com êxito, mas não pôde ser executado. Geralmente indica um problema com a consulta.
1001	Esse código é retornado quando o servidor conclui a execução transversal, mas falha ao serializar a resposta de volta para o cliente. Este erro pode acontecer quando a travessia gera um resultado complexo, que é muito grande ou não está em conformidade com a especificação do protocolo TinkerPop. O aplicativo deve simplificar a travessia quando encontrar esse erro.
1003	"Query exceeded memory limit. Bytes Consumed: XXX, Max: YYY" é retornado quando a travessia excede o limite de memória permitido. O limite de memória é de 2 GB por travessia.
1004	Esse código de status indica uma solicitação de gráfico malformada. A solicitação pode ser malformada quando falha na desserialização, o tipo sem valor está sendo desserializado como tipo de valor ou a operação gremlin sem suporte é solicitada. O aplicativo não deve tentar novamente a solicitação porque ela não será bem-sucedida.
1007	Normalmente, esse código de status é retornado com a mensagem de "Could not process request. Underlying connection has been closed."erro . Essa situação pode acontecer se o driver do cliente tenta usar uma conexão que está sendo fechada pelo servidor. O aplicativo deve tentar novamente a travessia em uma conexão diferente.
1008	O servidor Azure Cosmos DB para Gremlin pode encerrar conexões para reequilibrar o tráfego no cluster. Os drivers de cliente devem lidar com essa situação e usar apenas conexões em tempo real para enviar solicitações ao servidor. Ocasionalmente, os drivers de cliente podem não detetar que a conexão foi fechada. Quando o aplicativo encontra um erro, "Connection is too busy. Please retry after sometime or open more connections." ele deve tentar novamente atravessar em uma conexão diferente.
1009	A operação não foi concluída no tempo estipulado e foi cancelada pelo servidor. Otimize suas travessias para serem executadas rapidamente filtrando vértices ou arestas em cada salto de travessia para restringir o escopo de pesquisa. O tempo limite de solicitação padrão é de 60 segundos.

Exemplos

Um aplicativo cliente de exemplo baseado em Gremlin.Net que lê um atributo status:

// Following example reads a status code and total request charge from server response attributes.
// Variable "server" is assumed to be assigned to an instance of a GremlinServer that is connected to Azure Cosmos DB account.
using (GremlinClient client = new GremlinClient(server, new GraphSON2Reader(), new GraphSON2Writer(), GremlinClient.GraphSON2MimeType))
{
  ResultSet<dynamic> responseResultSet = await GremlinClientExtensions.SubmitAsync<dynamic>(client, requestScript: "g.V().count()");
  long statusCode = (long)responseResultSet.StatusAttributes["x-ms-status-code"];
  double totalRequestCharge = (double)responseResultSet.StatusAttributes["x-ms-total-request-charge"];

  // Status code and request charge are logged into application telemetry.
}

Um exemplo que demonstra como ler o atributo status do cliente Java Gremlin:

try {
  ResultSet resultSet = this.client.submit("g.addV().property('id', '13')");
  List<Result> results = resultSet.all().get();

  // Process and consume results

} catch (ResponseException re) {
  // Check for known errors that need to be retried or skipped
  if (re.getStatusAttributes().isPresent()) {
    Map<String, Object> attributes = re.getStatusAttributes().get();
    int statusCode = (int) attributes.getOrDefault("x-ms-status-code", -1);

    // Now we can check for specific conditions
    if (statusCode == 409) {
        // Handle conflicting writes
      }
    }

    // Check if we need to delay retry
    if (attributes.containsKey("x-ms-retry-after-ms")) {
      // Read the value of the attribute as is
      String retryAfterTimeSpan = (String) attributes.get("x-ms-retry-after-ms"));

      // Convert the value into actionable duration
			LocalTime locaTime = LocalTime.parse(retryAfterTimeSpan);
			Duration duration = Duration.between(LocalTime.MIN, locaTime);

      // Perform a retry after "duration" interval of time has elapsed
    }
  }
}

Próximos passos

• Códigos de estado HTTP do Azure Cosmos DB
• Cabeçalhos de resposta REST comuns do Azure Cosmos DB
• Requisitos do provedor de driver do TinkerPop Graph