Condividi tramite


Intestazioni di risposta del server Azure Cosmos DB per Gremlin

SI APPLICA A: Gremlin

Questo articolo illustra le intestazioni restituite dal server Azure Cosmos DB per Gremlin al chiamante al momento dell'esecuzione della richiesta. Queste intestazioni sono utili per la risoluzione dei problemi relativi alle prestazioni delle richieste, creando un'applicazione che si integra in modo nativo con il servizio Azure Cosmos DB e semplificando il supporto tecnico.

Tenere presente che l'assunzione di dipendenze da queste intestazioni limita la portabilità dell'applicazione ad altre implementazioni Gremlin. In cambio, si sta ottenendo un'integrazione più stretta con Azure Cosmos DB per Gremlin. Queste intestazioni non sono uno standard TinkerPop.

Intestazioni

Intestazione Type Valore di esempio Se incluso Spiegazione
x-ms-request-charge double 11.3243 Success and Failure Quantità di velocità effettiva di raccolta o database utilizzata nelle unità richiesta (UR/s o UR) per un messaggio di risposta parziale. Questa intestazione è presente in ogni continuazione per le richieste con più blocchi. Riflette l'addebito di un determinato blocco di risposta. Solo per le richieste costituite da un singolo blocco di risposta, questa intestazione corrisponde al costo totale dell'attraversamento. Tuttavia, per la maggior parte degli attraversamenti complessi questo valore rappresenta un costo parziale.
x-ms-total-request-charge double 423.987 Success and Failure Quantità di velocità effettiva di raccolta o database utilizzata nelle unità richiesta (UR/s o UR) per l'intera richiesta. Questa intestazione è presente in ogni continuazione per le richieste con più blocchi. Indica l'addebito cumulativo dall'inizio della richiesta. Il valore di questa intestazione nell'ultimo blocco indica l'addebito completo della richiesta.
x-ms-server-time-ms double 13,75 Success and Failure Questa intestazione è inclusa a scopo di risoluzione dei problemi di latenza. Indica la quantità di tempo, in millisecondi, che azure Cosmos DB per il server Gremlin ha impiegato per l'esecuzione e produrre un messaggio di risposta parziale. L'uso del valore di questa intestazione e il confronto con le applicazioni di latenza delle richieste complessive possono calcolare il sovraccarico della latenza di rete.
x-ms-total-server-time-ms double 130.512 Success and Failure Tempo totale, in millisecondi, impiegato dal server Azure Cosmos DB per Gremlin per eseguire l'intero attraversamento. Questa intestazione è inclusa in ogni risposta parziale. Rappresenta il tempo di esecuzione cumulativo dall'inizio della richiesta. L'ultima risposta indica il tempo di esecuzione totale. Questa intestazione è utile per distinguere tra client e server come origine della latenza. È possibile confrontare il tempo di esecuzione dell'attraversamento nel client con il valore di questa intestazione.
x-ms-status-code long 200 Success and Failure L'intestazione indica il motivo interno per il completamento o la terminazione della richiesta. È consigliabile esaminare il valore di questa intestazione e intraprendere un'azione correttiva.
x-ms-substatus-code long 1003 Solo errore Azure Cosmos DB è un database multimodelli basato sul livello di archiviazione unificato. Questa intestazione contiene informazioni aggiuntive sul motivo dell'errore quando si verifica un errore all'interno di livelli inferiori dello stack di disponibilità elevata. È consigliabile archiviare questa intestazione e usarla quando si contatta il supporto tecnico di Azure Cosmos DB. Il valore di questa intestazione è utile per il tecnico di Azure Cosmos DB per la risoluzione dei problemi rapida.
x-ms-retry-after-ms string (TimeSpan) "00:00:03.9500000" Solo errore Questa intestazione è una rappresentazione di stringa di un tipo TimeSpan .NET. Questo valore verrà incluso solo nelle richieste non riuscite a causa dell'esaurimento della velocità effettiva con provisioning. L'applicazione deve ripetere l'attraversamento dopo il periodo di tempo indicato.
x-ms-activity-id string (Guid) "A9218E01-3A3A-4716-9636-5BD86B056613" Success and Failure L'intestazione contiene un identificatore univoco lato server di una richiesta. A ogni richiesta viene assegnato un identificatore univoco dal server a scopo di rilevamento. Le applicazioni devono registrare gli identificatori di attività restituiti dal server per le richieste su cui i clienti potrebbero voler contattare il supporto tecnico. Il personale di supporto di Azure Cosmos DB può trovare richieste specifiche da questi identificatori nei dati di telemetria del servizio Azure Cosmos DB.

Codici di stato

Di seguito sono elencati i codici più comuni restituiti per x-ms-status-code l'attributo di stato dal server.

Status Spiegazione
401 Il messaggio "Unauthorized: Invalid credentials provided" di errore viene restituito quando la password di autenticazione non corrisponde alla chiave dell'account Azure Cosmos DB. Passare all'account Azure Cosmos DB per Gremlin nella portale di Azure e verificare che la chiave sia corretta.
404 Operazioni simultanee che tentano di eliminare e aggiornare contemporaneamente lo stesso bordo o vertice. Il messaggio di errore "Owner resource does not exist" indica che il database o la raccolta specificati non sono corretti nei parametri di connessione in formato /dbs/<database name>/colls/<collection or graph name>.
409 "Conflicting request to resource has been attempted. Retry to avoid conflicts." Generalmente questo si verifica quando nel grafo esiste già un vertice o un arco con un identificatore.
412 Il codice di stato è completato con il messaggio di "PreconditionFailedException": One of the specified pre-condition is not meterrore . Questo errore è indicativo di una violazione del controllo della concorrenza ottimistica tra la lettura di un bordo o un vertice e la scrittura nell'archivio dopo la modifica. La maggior parte delle situazioni comuni in cui si verifica questo errore è la modifica delle proprietà, ad esempio g.V('identifier').property('name','value'). Il motore Gremlin legge il vertice, lo modifica e lo riscrive. Se è in esecuzione un'altra attraversamento in parallelo cercando di scrivere lo stesso vertice o uno dei bordi, uno di essi riceverà questo errore. L'applicazione deve inviare nuovamente l'attraversamento al server.
429 La richiesta è stata limitata e deve essere ritentata dopo il valore in x-ms-retry-after-ms
500 Il messaggio di errore contenente "NotFoundException: Entity with the specified id does not exist in the system." indica che sono stati ricreati un database e/o una raccolta con lo stesso nome. Questo errore scomparirà entro 5 minuti man mano che la modifica si propaga e invalida le cache in diversi componenti di Azure Cosmos DB. Per evitare il problema, usare ogni volta i nomi univoci per database e raccolte.
1000 Questo codice di stato viene restituito quando il server ha analizzato correttamente un messaggio ma non è stato in grado di eseguire. In genere indica un problema con la query.
1001 Questo codice viene restituito quando il server completa l'esecuzione dell'attraversamento, ma non riesce a serializzare la risposta al client. Questo errore può verificarsi quando l'attraversamento genera risultati complessi, troppo grandi o non conformi alla specifica del protocollo TinkerPop. L'applicazione deve semplificare l'attraversamento quando si verifica questo errore.
1003 "Query exceeded memory limit. Bytes Consumed: XXX, Max: YYY" viene restituito quando l'attraversamento supera il limite di memoria consentito. Il limite di memoria è di 2 GB per attraversamento.
1004 Questo codice di stato indica una richiesta di grafico in formato non valido. La richiesta può essere in formato non valido quando non riesce la deserializzazione, il tipo non valore viene deserializzato come tipo di valore o come operazione gremlin non supportata richiesta. L'applicazione non deve ritentare la richiesta perché non avrà esito positivo.
1007 In genere, questo codice di stato viene restituito con il messaggio di "Could not process request. Underlying connection has been closed."errore . Questa situazione può verificarsi se il driver client tenta di usare una connessione chiusa dal server. L'applicazione deve ritentare l'attraversamento in una connessione diversa.
1008 Il server Azure Cosmos DB per Gremlin può terminare le connessioni per ribilanciare il traffico nel cluster. I driver client devono gestire questa situazione e usare solo connessioni dinamiche per inviare richieste al server. In alcuni casi i driver client potrebbero non rilevare che la connessione è stata chiusa. Quando si verifica un errore, "Connection is too busy. Please retry after sometime or open more connections." l'applicazione deve ripetere l'attraversamento in una connessione diversa.
1009 L'operazione non è stata completata nel tempo assegnato ed è stata annullata dal server. Ottimizzare gli attraversamenti per l'esecuzione rapida filtrando vertici o archi su ogni hop di attraversamento per restringere l'ambito di ricerca. Il valore predefinito del timeout della richiesta è 60 secondi.

Esempi

Applicazione client di esempio basata su Gremlin.Net che legge un attributo di stato:

// 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.
}

Esempio che illustra come leggere l'attributo di stato dal client 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
    }
  }
}

Passaggi successivi