共用方式為

將數據從 Azure Cosmos DB 內嵌至 Azure 數據總管

  • 發行項

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

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

使用 Cosmos DB 變更回饋數據連線的兩種主要情境如下：

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

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

步驟 1： 選擇 Azure 數據總管數據表並設定其數據表對應

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

步驟 3： 測試數據連線

必要條件

步驟 1：選擇 Azure 數據總管數據表並設定其數據表對應

建立數據連線之前，請先建立數據表，在其中儲存內嵌的數據，並套用符合來源 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 數據總管 Web UI 中，從左側導覽功能表中選取 [查詢]，然後選取您要在其中建立數據表的資料庫。

  2. 執行下列命令以建立名為 TestTable 的數據表。

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

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

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

    Cosmos DB 屬性 資料表資料行 轉換
    id 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 數據總管資料庫。
    數據連線名稱 指定數據連線的名稱。
    訂用帳戶 選取包含Cosmos DB NoSQL 帳戶的訂用帳戶。
    Cosmos DB 帳戶 選擇您要從中擷取數據的 Cosmos DB 帳戶。
    SQL 資料庫 選擇您要從中擷取資料的 Cosmos DB 資料庫。
    SQL 容器 選擇您要從中擷取資料的 Cosmos DB 容器。
    資料表名稱 指定要內嵌數據的 Azure 資料 總管資料表名稱 。
    對應名稱 選擇性地指定要 用於數據連線的對應名稱 。

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

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

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

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

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

步驟 3：測試數據連線

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

    {
    "name":"Cousteau"
}

  2. 在 Azure 數據總管 Web UI 中，執行下列查詢：

    TestTable

    結果集應顯示下列圖片：

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

注意

Azure 數據總管具有佇列數據擷取的匯總（批處理）原則，其設計目的是優化擷取程式。 默認批處理原則設定為一旦批次的下列其中一個條件成立，就會封存批次：延遲時間上限為 5 分鐘、總大小為 1 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 Orange 更新 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 Orange 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 的更新，這是從 Pink 到 Carmine 之屬性 foo 的更新。

    由於此案例，數據連接器可能會遺漏一些中繼文件變更。 例如，如果數據連線服務關閉幾分鐘，或文件變更的頻率高於 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。

相關內容