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

Important

您是否正在尋找一種適用於高擴展性場景的資料庫解決方案，且具有 99.999% 可用性的服務等級協定（SLA）、即時自動擴展，以及跨多個區域的自動容錯切換？ 考慮使用Azure Cosmos DB作為NoSQL的選擇。

您是否想要實作線上分析處理 （OLAP） 圖表或移轉現有的 Apache Gremlin 應用程式？ 考慮Microsoft Fabric中的圖表。

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

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

標題

Header	類型	範例值	包含時	Explanation
x-ms-請求收費	double	11.3243	成功與失敗	部分回應訊息所耗用的集合或資料庫輸送量，以 要求單位 （RU/秒或 RU） 為單位。 此標頭存在於具有多個區塊之要求的每個接續中。 它反映了特定響應塊的費用。 只有針對包含單一回應區塊的請求，此標頭才會符合周遊的總成本。 不過，對於大部分的複雜周遊，此值代表部分成本。
x-ms-總請求費用	double	423.987	成功與失敗	整個要求所耗用的集合或資料庫輸送量，以 要求單位 （RU/秒或 RU） 為單位。 此標頭存在於具有多個區塊之要求的每個接續中。 它表示自請求開始以來的累計費用。 最後一個區塊中此標頭的值表示完整的請求費用。
x-ms-服務器時間-ms	double	13.75	成功與失敗	包含此標頭以用於延遲疑難排解。 它指出適用於 Gremlin 的 Azure Cosmos DB 伺服器執行並產生部分回應訊息所花費的時間量 （以毫秒為單位）。 使用此標頭的值，並將其與整體要求延遲應用程式進行比較，可以計算網路延遲額外負荷。
x-ms-總計-伺服器-時間-ms	double	130.512	成功與失敗	適用於 Gremlin 的 Azure Cosmos DB 伺服器執行整個周遊所花費的總時間 （以毫秒為單位）。 此標頭會包含在每個部分回應中。 它代表自請求開始以來的累計執行時間。 最後一個回應表示總執行時間。 此標頭可用於區分用戶端和伺服器作為延遲來源。 您可以將用戶端上的周遊執行時間與此標頭的值進行比較。
x-ms-狀態代碼	long	200	成功與失敗	標頭指出要求完成或終止的內部原因。 建議應用程式查看此標頭的值並採取更正動作。
x-ms-子狀態代碼	long	1003	僅限失敗	Azure Cosmos DB 是建置在統一儲存體層之上的多模型資料庫。 此標頭包含有關在高可用性堆疊的較低層內發生故障時失敗原因的其他見解。 建議應用程式儲存此標頭，並在連絡 Azure Cosmos DB 客戶支援時使用它。 此標頭的值對於 Azure Cosmos DB 工程師很有用，可以快速進行疑難排解。
x-ms-後重試	字串 （TimeSpan）	"00:00:03.9500000"	僅限失敗	此標頭是 .NET TimeSpan 類型的字串表示法。 此值只會包含在因佈建輸送量耗盡而失敗的請求中。 申請應在指示的時間段後再次重新提交遍歷。
x-ms-活動識別碼	string （Guid）	“A9218E01-3A3A-4716-9636-5BD86B056613”	成功與失敗	標頭包含請求的唯一伺服器端識別碼。 伺服器為每個請求分配一個唯一的識別碼以進行追蹤。 應用程式應該記錄伺服器所傳回的活動識別碼，以取得客戶可能想要連絡客戶支援的要求。 Azure Cosmos DB 支援人員可以在 Azure Cosmos DB 服務遙測中，依這些識別碼尋找特定要求。

狀態碼

下面列出伺服器針對狀態屬性傳回的最 x-ms-status-code 常見代碼。

狀態	Explanation
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 秒。

Samples

以讀取一個狀態屬性的 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
    }
  }
}