從 Azure Cosmos DB 匯入

重要

Machine Learning 工作室 (傳統) 的支援將於 2024 年 8 月 31 日結束。 建議您在該日期之前轉換成 Azure Machine Learning。

自 2021 年 12 月 1 日起，您將無法建立新的 Machine Learning 工作室 (傳統) 資源。 在 2024 年 8 月 31 日之前，您可以繼續使用現有的 Machine Learning 工作室 (傳統) 資源。

• 請參閱將機器學習專案從 ML 工作室 (傳統) 移至 Azure Machine Learning 的相關資訊。
• 深入瞭解Azure Machine Learning。

ML 工作室 (傳統) 文件即將淘汰，未來將不再更新。

本文說明如何使用機器學習 Studio (傳統) 中的 [匯入資料] 模組，從 Azure Cosmos DB 匯入資料，以在機器學習實驗中使用。

注意

適用于：僅限機器學習 Studio (傳統)

Azure Machine Learning 設計工具中提供類似的拖放模組。

Azure Cosmos DB使用彈性的資料模型來支援 NoSQL 資料庫儲存體。 在此資料存放區中使用 SQL api 來進行機器學習的優點包括：快速且可預測的效能、自動調整、全域散發，以及豐富的查詢功能。

搭配 Azure SQL Database，此選項可讓您動態篩選傳入的資料集。

瞭解運作方式：瞭解 Azure Cosmos DB

• 若要開始使用 Azure Cosmos DB 中的資料進行機器學習，您必須能夠存取包含相關檔集合的現有 Azure Cosmos DB 帳戶。

注意

機器學習 Studio (傳統) 中的使用者介面仍會在許多地方使用名稱 DocumentDB。 因此，即使 API 已併入 Azure Cosmos DB 中，您仍可繼續看到 DocumentDB 的參考。

如何搭配 Azure Cosmos DB 使用匯入資料

強烈建議您在匯入前先分析資料，以確保架構如預期般運作。 匯入程式會掃描部分的標頭資料列來判斷架構，但之後的資料列可能會包含額外的資料行或造成錯誤的資料。

使用 wizard 匯入資料

此課程模組提供新的 wizard，可協助您選擇儲存選項、從現有的訂用帳戶和帳戶中選取，以及快速設定所有選項。

1. 將 [匯 入資料 ] 模組新增至您的實驗。 您可以在 資料輸入和輸出下找到此模組。

2. 按一下 [ 啟動匯入資料] ，並遵循提示進行。

3. 設定完成時，若要實際將資料複製到您的實驗中，請以滑鼠右鍵按一下模組，然後選取 [ 執行選取的]。

提示

如果您需要編輯現有的資料連線，則嚮導會載入所有先前的設定詳細資料。 您不需要從頭開始。

在 [匯入資料] 模組中手動設定屬性

下列步驟描述如何手動設定匯入來源。

1. 將 [匯 入資料 ] 模組新增至您的實驗。 您可以在 [ 資料輸入] 和 [輸出 ] 分類中找到此模組。

2. 針對 [ 資料來源]，選取 [ Azure DocumentDB]。

   您可能需要提供檔資料庫的連接資訊。

   提示

   在機器學習 Studio (傳統) 中尋找選項的名稱，以在日後變更。 匯入功能不受名稱變更影響。

3. 針對 端點 URL，在 Azure 入口網站中，按一下 [ 金鑰]，然後複製頁面頂端的 [ URI ] 欄位的內容。

4. 針對 [ 資料庫識別碼]，貼上要使用的資料庫名稱。

   若要從 Azure 入口網站取得資料庫名稱，請按一下 [ Document Explorer]。 您可以在此窗格中，查看資料庫和集合的清單。

5. 針對 DocumentDB 金鑰，貼上帳戶的存取金鑰。

   若要尋找金鑰，請按一下 [ 金鑰]，然後複製 [ 主要金鑰 ] 或 [ 次要金鑰 ] 欄位的內容。

6. 在 [ 集合識別碼] 中，輸入集合的名稱，如指定的 CosmosDB 資料庫中所示。

7. 使用SQL 查詢和SQL 查詢參數選項，定義資料的 SQL 查詢和篩選準則。

   針對SQL 查詢，輸入定義要從集合中取出之資料的查詢。 建議您事先使用 查詢瀏覽器 來建立和測試您的 CosmosDB 查詢。

   針對SQL 查詢參數，請提供 JSON 格式的運算式，可用來動態篩選傳回的資料。 當您在 Web 服務中執行實驗時，通常會提供參數值的實際值。

   如果您使用參數，就必須將篩選變數名稱定義為 [ SQL 查詢] 文字方塊中指定之 WHERE 子句的一部分。

   如果您未指定篩選運算式，預設值會設定為 " {} "，而且會傳回所有記錄。

   如需有關 CosmosDB 上 SQL 查詢的範例、已知問題和其他建議，請參閱技術提示一節。

8. 如果您想要重複使用現有的結果，請選取 [使用快取的 結果 ] 選項。

   如果您取消選取此選項，就會在每次執行實驗時從來源讀取資料，不論資料是否相同。

   機器學習無法將快取的資料與 CosmosDB 帳戶中的資料進行比較。 因此，沒有任何方法可從機器學習執行累加式更新。

   如果您只想要在資料變更時重新匯入，您必須在另一個應用程式中定義該邏輯（例如 Azure Data Factory）。 如需詳細資訊，請參閱使用 Azure Data Factory 將資料移入和移出 Azure Cosmos DB。

9. 執行實驗，或只選取 [匯 入資料 ] 模組，然後按一下 [ 執行選取]。

結果

執行模組或實驗之後，您可以用滑鼠右鍵按一下模組的輸出，以表格格式將結果視覺化。

若要在您的機器學習工作區中，將此資料的快照集作為資料集來捕捉，您可以用滑鼠右鍵按一下模組的輸出，然後選取 [另存為資料集]。 不過，這樣做只會捕捉匯入時可用的資料。 如果資料預期會經常變更，請視需要重新執行匯 入資料 。

範例

如需如何使用 Azure Cosmos DB 作為機器學習資料來源的詳細逐步解說，請參閱Azure AI 資源庫。

• Azure Cosmos DB 的 SQL 查詢：本文說明如何在 Azure Cosmos DB 資料上執行 SQL 查詢。

技術說明

本節包含先進的設定選項以及常見問題的解答。

簡單和參數化查詢的範例

假設您只想要在火山上使用10000英尺高度的資料。

簡單查詢

在 [ SQL 查詢] 文字方塊中，貼上下列查詢：Select * from volcanodb where volcanodb.Elevation < 10000

在此情況下，篩選運算式的值會設定為 " {} "，而且會傳回所有記錄。

參數化查詢

若只要取得與特定國家/地區相關的火山資料，您可以在執行時間將 country 值指定為傳遞給查詢的參數。 這需要這些變更：

1. 在 [ SQL 查詢] 文字方塊中，定義變數以套用至 Country 欄位做為 SQL 查詢的一部分：

   Select * from volcanodb where volcanodb.Country = @param1

2. 在 [ SQL 查詢參數] 文字方塊中，以 JSON 格式指定參數名稱和其值，如下所示：

   {"@param1":"Turkey"}

資源

如果您沒有現有的檔存放區，請參閱這些文章以開始使用。

• Azure Cosmos DB︰使用 .NET 和 Azure 入口網站建置 SQL API Web 應用程式

• 快速入門：建置 .NET 主控台應用程式來管理 Azure Cosmos DB SQL API 資源

• Azure Cosmos DB 遷移工具

資料移轉和查詢語法說明

如需 JSON 資料存放區的查詢範例，請下載Azure Cosmos DB 查詢功能提要頁面。

如果您需要將內容上傳至 Azure Cosmos DB，我們建議Azure Cosmos DB 的遷移工具。 它會驗證、上傳和編制資料的索引。 此工具支援多個來源，包括 MongoDB、Amazon DynamoDB、HBase、SQL Server 資料庫和 CSV 檔案。

使用無架構的查詢

如果資料一致且可預測，您可以使用類似 SQL 的語法，例如 SELECT * FROM <document collection> 。 這稱為無 架構的查詢 ，因為您未命名要傳回的確切屬性。 這類查詢會傳回所指定集合中的所有欄位和所有資料列。

但是，如果檔的架構不一致，則未指定架構可能會導致非預期的結果或執行階段錯誤。 這是因為「匯 入資料 」模組會嘗試根據預先決定的資料列數目推斷架構，如下所示：

1. 未指定任何屬性時，模組會掃描 CosmosDB 資料庫中的第一個資料列。
2. 此模組會根據屬性來建立資料行名稱，並根據範例資料列猜測資料行資料類型。
3. 如果以後的資料列包含任何新的或不同的屬性，就會產生執行階段錯誤。

因此，建議您一律指定要從 CosmosDB 資料存放區傳回的屬性和值。 例如，我們建議您將查詢取出的所有屬性命名為（如下所示），而不是使用 SELECT * 語法：

SELECT MyTable.Gender, MyTable.Age, MyTable.Name FROM <document collection>

模組參數

下表只包含適用于 Azure Cosmos DB 選項的 [匯入資料] 模組的參數。

名稱	範圍	類型	必要	預設	描述
資料來源	list	HTTP	必要	無	資料來源可以是 HTTP、FTP、匿名 HTTPS 或 FTPS、azure BLOB 儲存體中的檔案、azure 資料表、Azure SQL Database、Hive 資料表、OData 端點或 Azure Cosmos dB。
端點 URL	任意	字串	必要	無	提供 Azure Cosmos DB 伺服器的 URI
資料庫識別碼	任意	字串	必要	無	提供 Azure Cosmos DB 資料庫的名稱
DocumentDB 金鑰	任意	SecureString	必要	無	為 Azure Cosmos DB 帳戶提供有效的 API 金鑰
集合識別碼	任意	字串	必要	無	在 Azure Cosmos DB 資料庫中提供集合的名稱
SQL 查詢	任意	字串	必要	無	SQL 查詢，指定要從 Azure Cosmos DB 資料存放區傳回的記錄

輸出

名稱	類型	說明
結果資料集	資料表	含下載資料的資料集

例外狀況

例外狀況	描述
錯誤 0003	如果一或多個輸入是 Null 或空白，就會發生例外狀況。
錯誤 0029	傳遞無效的 URI 時，就會發生例外狀況。
錯誤 0002	如果有一或多個參數無法剖析或從指定的類型轉換成目標方法所需的類型，就會發生例外狀況。
錯誤 0048	無法開啟檔案時，就會發生例外狀況。
錯誤 0049	無法剖析檔案時，就會發生例外狀況。

如需 Studio (傳統) 模組特定的錯誤清單，請參閱機器學習錯誤碼。

如需 API 例外狀況的清單，請參閱機器學習 REST API 錯誤碼。

另請參閱

匯入資料
匯出資料
透過 HTTP 從 Web URL 匯入
從 Hive 查詢匯入
從 Azure SQL Database 匯入
從 Azure Blob 儲存體匯入
從資料摘要提供者匯入
從內部部署 SQL Server 資料庫匯入