Share via

將數據從 Azure Cosmos DB 擷取至 Azure Data Explorer

  • 發行項

Azure Data Explorer 支援使用變更摘要從適用於 NoSql 的 Azure Cosmos DB 擷取數據。 Cosmos DB 變更摘要數據連線是一種擷取管線，可接聽 Cosmos DB 變更摘要，並將數據內嵌到您的 Data Explorer 數據表。 變更摘要會接聽新的和更新的檔，但不會記錄刪除。 如需 Azure Data Explorer 中數據擷取的一般資訊，請參閱 Azure Data Explorer 數據擷取概觀。

每個數據連線都會接聽特定的 Cosmos DB 容器，並將數據內嵌至指定的數據表， (多個連接可以在單一數據表中內嵌) 。 啟用串流擷取) 和佇列擷取時，擷取方法支援串流擷取 (。

在本文中，您將瞭解如何設定 Cosmos DB 變更摘要數據連線，以使用系統受控識別將數據內嵌至 Azure Data Explorer。 開始之前，請先檢 閱考慮 事項。

使用下列步驟來設定連接器：

步驟 1：選擇 Azure Data Explorer 數據表，並設定其數據表對應

步驟 2： 建立 Cosmos DB 數據連線

步驟 3： 測試數據連線

必要條件

步驟 1：選擇 Azure Data Explorer 資料表並設定其數據表對應

建立數據連線之前，請先建立數據表，在其中儲存擷取的數據，並在來源 Cosmos DB 容器中套用符合架構的對應。 如果您的案例需要多個字段的簡單對應，您可以使用 更新原則來轉換和對應 從變更摘要擷取的數據。

以下顯示 Cosmos DB 容器中專案的範例架構：

{
    "id": "17313a67-362b-494f-b948-e2a8e95e237e",
    "name": "Cousteau",
    "_rid": "pL0MAJ0Plo0CAAAAAAAAAA==",
    "_self": "dbs/pL0MAA==/colls/pL0MAJ0Plo0=/docs/pL0MAJ0Plo0CAAAAAAAAAA==/",
    "_etag": "\"000037fc-0000-0700-0000-626a44110000\"",
    "_attachments": "attachments/",
    "_ts": 1651131409
}

使用下列步驟來建立資料表並套用資料表對應：

  1. 在 Azure Data Explorer Web UI 中，從左側導覽功能表中選取 [查詢]，然後選取您要建立數據表的資料庫。

  2. 執行下列命令來建立名為 TestTable 的資料表。

    .create table TestTable(Id:string, Name:string, _ts:long, _timestamp:datetime)

  3. 執行下列命令以建立數據表對應。

    此命令會將Cosmos DB JSON 檔案中的自訂屬性對應至 TestTable 資料表中的數據行，如下所示：

    Cosmos DB 屬性 表格欄位 轉換
    id 識別碼 無
    name 名稱 無
    _Ts _ts 無
    _Ts _時間 戳 用來DateTimeFromUnixSeconds轉換_ts (UNIX 秒) _timestamp (datetime) )

    注意

    我們建議使用下列時間戳數據行：

    • _ts：使用此數據行來協調Cosmos DB的數據。
    • _timestamp：使用此數據行在 Kusto 查詢中執行有效率的時間篩選。 如需詳細資訊，請參閱 查詢最佳做法。
    .create table TestTable ingestion json mapping "DocumentMapping"
```
[
    {"column":"Id","path":"$.id"},
    {"column":"Name","path":"$.name"},
    {"column":"_ts","path":"$._ts"},
    {"column":"_timestamp","path":"$._ts", "transform":"DateTimeFromUnixSeconds"}
]
```

使用更新原則轉換和對應數據

如果您的案例需要多個字段的簡單對應，您可以使用更新原則來轉換和對應從變更摘要擷取的數據。

更新原則 是將數據內嵌至數據表時轉換數據的方法。 它們是以 Kusto 查詢語言 撰寫，並在擷取管線上執行。 它們可用來從 Cosmos DB 變更摘要擷取轉換數據，例如在下列案例中：

  • 您的檔包含數位，使用運算符在多個數據列 mv-expand 中轉換時，查詢會比較容易。
  • 您要篩選出檔案。 例如，您可以使用 運算符，依類型 where 篩選出檔。
  • 您有無法在數據表對應中表示的複雜邏輯。

如需如何建立和管理更新原則的資訊，請參閱 更新原則概觀。

步驟 2：建立 Cosmos DB 數據連線

您可以使用下列方法來建立資料連接器：

  1. 在 Azure 入口網站 中，移至您的叢集概觀頁面，然後選取 [開始使用] 索引卷標。

  2. 在 [ 數據擷取] 圖格上，選取 [建立數據連線>Cosmos DB]。

    [開始使用] 索引標籤的螢幕快照，其中顯示 [建立Cosmos DB資料連線] 選項。

  3. 在 [Cosmos DB 建立數據連線 ] 窗格中，以數據表中的資訊填寫表單：

    數據連線窗格的螢幕快照，其中顯示具有值的表單域。

    欄位 描述
    資料庫名稱 選擇您要擷取資料的 Azure Data Explorer 資料庫。
    資料連線名稱 指定數據連接的名稱。
    訂用帳戶 選取包含Cosmos DB NoSQL 帳戶的訂用帳戶。
    Cosmos DB 帳戶 選擇您要從中擷取數據的 Cosmos DB 帳戶。
    SQL 資料庫 選擇您要從中擷取資料的 Cosmos DB 資料庫。
    SQL 容器 選擇您要從中擷取資料的 Cosmos DB 容器。
    資料表名稱 指定您要內嵌資料的 Azure Data Explorer 資料表名稱。
    對應名稱 選擇性地指定要用於數據連接的 對應名稱 。

  4. 或者，在 [ 進階設定 ] 區段下，執行下列動作：

    1. 指定 事件擷取開始日期。 這是連接器開始擷取數據的時間。 如果您未指定時間，連接器就會開始從您建立數據連線的時間擷取數據。 建議的日期格式是 ISO 8601 UTC 標準，如下所示： yyyy-MM-ddTHH:mm:ss.fffffffZ。

    2. 選取 [用戶指派] ，然後選取身分識別。 根據預設，聯機會使用 系統指派的 受控識別。 如有必要，您可以使用 使用者指派的 身分識別。

      數據連線窗格的螢幕快照，其中顯示 [進階設定]。

  5. 選取 [建立 ] 以建立數據連線。

步驟 3：測試數據連線

  1. 在 Cosmos DB 容器中，插入下列檔：

    {
    "name":"Cousteau"
}

  2. 在 Azure Data Explorer Web UI 中，執行下列查詢：

    TestTable

    結果集應顯示下列圖片：

    結果窗格的螢幕快照，其中顯示內嵌的檔。

注意

Azure Data Explorer 具有佇列數據擷取的匯總 (批處理) 原則，其設計目的是優化擷取程式。 默認批處理原則是針對批次設定為密封批次一次，一旦批次符合下列其中一個條件：延遲時間上限為 5 分鐘、大小總計為一 GB 或 1000 個 Blob。 因此，您可能會遇到延遲。 如需詳細資訊，請參閱批次原則。 若要減少延遲，請將您的數據表設定為支援串流。 請參閱串流原則。

考量事項

下列考慮適用於 Cosmos DB 變更摘要：

  • 變更摘要不會公開 刪除 事件。

    Cosmos DB 變更摘要只會包含新的和更新的文件。 如果您需要知道已刪除的文件，可以設定讓摘要使用軟標記，以將 Cosmos DB 文件標示為已刪除。 屬性會新增至更新事件，指出檔是否已刪除。 然後，您可以在查詢中使用 where 運算符來篩選它們。

    例如，如果您將已刪除的屬性對應至名為 IsDeleted 的數據表資料行，您可以使用下列查詢篩選掉已刪除的檔案：

    TestTable
| where not(IsDeleted)

  • 變更摘要只會公開 檔的最新 更新。

    若要瞭解第二個考慮的影響，請檢查下列案例：

    Cosmos DB 容器包含 A 和 B 檔。下表顯示名為 foo 的屬性變更：

    文件識別碼 屬性 foo 事件 文件時間戳 (_ts)
    A 紅色 建立 10
    B 藍色 建立 20
    A 橙色 更新 30
    A 粉紅色 更新 40
    B 紫 更新 50
    A 胭脂紅 更新 50
    B NeonBlue 更新 70

    變更摘要 API 會定期由數據連接器輪詢，通常是每隔幾秒鐘。 每個輪詢都包含在呼叫之間的容器中發生的變更， 但每個檔只有最新版本的變更。

    為了說明此問題，請考慮具有時間戳 15、 35、 55 和 75 的 API 呼叫序列，如下表所示：

    API 呼叫時間戳 文件識別碼 屬性 foo 文件時間戳 (_ts)
    15 A 紅色 10
    35 B 藍色 20
    35 A 橙色 30
    55 B 紫 50
    55 A 胭脂紅 60
    75 B NeonBlue 70

    比較 API 結果與 Cosmos DB 檔案中所做的變更清單，您會注意到它們不相符。 記錄 A 的更新事件，在時間戳 40 的變更數據表中反白顯示，不會出現在 API 呼叫的結果中。

    為了瞭解事件未出現的原因，我們將檢查 API 呼叫在時間戳 35 和 55 之間的檔 A 變更。 在這兩個呼叫之間，檔 A 已變更兩次，如下所示：

    文件識別碼 屬性 foo 事件 文件時間戳 (_ts)
    A 粉紅色 更新 40
    A 胭脂紅 更新 50

    在時間戳 55 進行 API 呼叫時，變更摘要 API 會傳回最新版的檔。 在此案例中，最新版的檔 A 是時間戳 50 的更新，這是從[粉紅] 到 Carmine 屬性的更新。

    因此，數據連接器可能會遺漏一些中繼文件變更。 例如，如果數據連線服務關閉幾分鐘，或文件變更的頻率高於 API 輪詢頻率，可能會遺漏某些事件。 不過，會擷取每個檔的最新狀態。

  • 不支援刪除和重新建立 Cosmos DB 容器

    Azure 資料總管會藉由檢查摘要中的「位置」來追蹤變更摘要。 這會在容器的每個實體分割區上使用接續權杖來完成。 刪除/重新建立容器時，這些接續權杖會無效因此不會重設：您必須刪除並重新建立資料連線。

估計成本

使用 Cosmos DB 數據連線對 Cosmos DB 容器的要求 單位 (RU) 使用量有何影響？

連接器會在容器的每個實體分割區上叫用 Cosmos DB 變更摘要 API，最多一秒。 下列成本會與這些叫用相關聯：

成本 描述
固定成本 固定成本大約是每秒每個實體分割區 2 RU。
變動成本 可變成本大約是用來撰寫檔的 RU 2%，但視您的案例而有所不同。 例如，如果您將 100 份檔寫入 Cosmos DB 容器，則撰寫這些檔的成本為 1,000 RU。 使用連接器讀取這些文件的對應成本大約是寫入它們的成本 2%，大約是 20 RU。

相關內容