共用方式為

適用於 Gremlin 伺服器回應標頭的 Azure Cosmos DB

  • 發行項

適用於： Gremlin

本文涵蓋 Azure Cosmos DB for Gremlin 伺服器在要求執行時傳回給呼叫端的標頭。 這些標頭適用於針對要求效能進行疑難解答、建置以原生方式與 Azure Cosmos DB 服務整合的應用程式，以及簡化客戶支援。

請記住，依賴這些標頭，您會將應用程式的可移植性限製為其他 Gremlin 實作。 作為回報，您會與適用於 Gremlin 的 Azure Cosmos DB 緊密整合。 這些標頭不是 TinkerPop 標準。

標題

標題 類型 範例值 包含時 說明
x-ms-request-charge double 11.3243 成功和失敗 部分回應訊息的要求單位 （RU/秒或 RU） 所取用的集合或資料庫輸送量。 對於具有多個區塊的要求，每個接續中都會有此標頭。 它會反映特定響應區塊的費用。 只有包含單一響應區塊的要求，此標頭才會符合周游的總成本。 不過，對於大部分複雜的周遊而言，此值代表部分成本。
x-ms-total-request-charge double 423.987 成功和失敗 整個要求的要求單位（RU/秒或 RU）中取用的集合或資料庫輸送量數量。 對於具有多個區塊的要求，每個接續中都會有此標頭。 它表示自要求開始以來的累計費用。 最後一個區塊中的這個標頭值表示完整的要求費用。
x-ms-server-time-ms double 13.75 成功和失敗 此標頭隨附於延遲疑難解答用途。 它指出 Azure Cosmos DB for Gremlin 伺服器執行併產生部分回應訊息所花費的時間量，以毫秒為單位。 使用此標頭的值，並將其與整體要求延遲應用程式進行比較，即可計算網路等待時間額外負荷。
x-ms-total-server-time-ms double 130.512 成功和失敗 Gremlin 伺服器的 Azure Cosmos DB 執行整個周遊所花費的總時間，以毫秒為單位。 此標頭會包含在每個部分回應中。 它代表自要求開始以來的累計運行時間。 最後一個回應表示總運行時間。 此標頭有助於區分客戶端和伺服器作為延遲的來源。 您可以將用戶端上的周遊運行時間與這個標頭的值進行比較。
x-ms-status-code long 200 成功和失敗 標頭表示要求完成或終止的內部原因。 建議應用程式查看此標頭的值，並採取更正動作。
x-ms-substatus-code long 1003 僅限失敗 Azure Cosmos DB 是一個多模型資料庫，建置在整合儲存層之上。 此標頭包含有關在較低層級高可用性堆疊內發生失敗原因的其他見解。 建議應用程式儲存此標頭，並在連絡 Azure Cosmos DB 客戶支援時使用它。 此標頭的價值適用於 Azure Cosmos DB 工程師，以便快速進行疑難解答。
x-ms-retry-after-ms string （TimeSpan） "00:00:03.9500000" 僅限失敗 此標頭是 .NET TimeSpan 類型的字串表示。 此值只會包含在要求中，因為布建的輸送量耗盡而失敗。 在指示的時間週期之後，應用程式應該再次重新提交周遊。
x-ms-activity-id 字串 （Guid） “A9218E01-3A3A-4716-9636-5BD86B056613” 成功和失敗 標頭包含要求的唯一伺服器端標識碼。 每個要求都會由伺服器指派唯一標識符，以供追蹤之用。 應用程式應該記錄伺服器傳回的活動標識碼，以取得客戶可能想要連絡客戶支持的相關要求。 Azure Cosmos DB 支援人員可以在 Azure Cosmos DB 服務遙測中找到這些標識碼的特定要求。

狀態碼

伺服器針對 status 屬性傳 x-ms-status-code 回的最常見代碼如下所列。

狀態 說明
401 驗證密碼不符合 Azure Cosmos DB 帳戶密鑰時，會傳回錯誤訊息 "Unauthorized: Invalid credentials provided" 。 流覽至 Azure 入口網站 中適用於 Gremlin 的 Azure Cosmos DB 帳戶，並確認密鑰正確無誤。
404 同時嘗試刪除和更新相同邊緣或頂點的並行作業。 錯誤訊息 "Owner resource does not exist" 指出指定的資料庫或集合格式的連接參數 /dbs/<database name>/colls/<collection or graph name> 不正確。
409 "Conflicting request to resource has been attempted. Retry to avoid conflicts." 這通常會發生在圖形中已有標識碼的頂點或邊緣時。
412 狀態代碼會補充錯誤訊息 "PreconditionFailedException": One of the specified pre-condition is not met。 此錯誤表示讀取邊緣或頂點之間的開放式並行控制違規，並在修改後將其寫回存放區。 發生此錯誤的最常見情況是屬性修改，例如 g.V('identifier').property('name','value')。 Gremlin 引擎會讀取頂點、修改頂點，並將它寫回。 如果有另一個周游以平行方式執行，嘗試寫入相同的頂點或邊緣，其中一個將會收到此錯誤。 應用程式應該再次提交周遊至伺服器。
429 要求已節流處理，且應在 x-ms-retry-after-ms 中的值 之後重試
500 包含 "NotFoundException: Entity with the specified id does not exist in the system." 的錯誤訊息表示已使用相同的名稱重新建立資料庫和/或集合。 此錯誤會在 5 分鐘內消失，因為變更會傳播並使不同 Azure Cosmos DB 元件中的快取失效。 若要避免此問題，請每次使用唯一的資料庫和集合名稱。
1000 當伺服器成功剖析訊息但無法執行時，就會傳回此狀態代碼。 它通常表示查詢有問題。
1001 當伺服器完成周遊執行，但無法將回應串行化回用戶端時，就會傳回此程序代碼。 當周遊產生複雜結果時，可能會發生此錯誤，其太大或不符合 TinkerPop 通訊協議規格。 應用程式應該在遇到此錯誤時簡化周遊。
1003 "Query exceeded memory limit. Bytes Consumed: XXX, Max: YYY" 當周游超過允許的記憶體限制時，會傳回 。 每個周遊的記憶體限制為 2 GB 。
1004 此狀態代碼表示格式不正確的圖形要求。 當要求無法還原串行化、非實值型別還原串行化為實值類型或要求的不支援 gremlin 作業時，可能會格式不正確。 應用程式不應該重試要求，因為它不會成功。
1007 通常會傳回此狀態代碼，並出現錯誤訊息 "Could not process request. Underlying connection has been closed."。 如果客戶端驅動程式嘗試使用伺服器正在關閉的連線，就可能發生這種情況。 應用程式應該在不同的連線上重試周遊。
1008 適用於 Gremlin 伺服器的 Azure Cosmos DB 可以終止連線，以重新平衡叢集中的流量。 用戶端驅動程式應該處理這種情況，並且只使用即時連線將要求傳送至伺服器。 偶爾客戶端驅動程式可能不會偵測到連線已關閉。 當應用程式發生錯誤時， "Connection is too busy. Please retry after sometime or open more connections." 應該在不同的連線上重試周遊。
1009 作業未在分配的時間內完成，而且已由伺服器取消。 在周遊的每個躍點上篩選頂點或邊緣，以縮小搜尋範圍，將周遊優化以快速執行。 要求逾時預設值為 60 秒。

範例

以讀取狀態屬性 Gremlin.Net 為基礎的範例客戶端應用程式：

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

示範如何從 Gremlin Java 用戶端讀取狀態屬性的範例：

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

下一步