快速入門:使用 Azure Cosmos DB SQL API 帳戶建置 Python 應用程式

適用於: SQL API

在本快速入門中,您會從 Azure 入口網站以及從 Visual Studio Code 搭配從 GitHub 複製的 Python 應用程式,來建立和管理 Azure Cosmos DB SQL API 帳戶。 Azure Cosmos DB 是多模型的資料庫服務,可讓您快速建立及查詢具有全域散發和水平調整功能的文件、資料表、索引鍵/值及圖形資料庫。

必要條件

Python 2.x 支援的重要更新

從 2022 年 1 月 1 日開始,此 SDK 的新版本不再支援 Python 2.x。 請檢查 CHANGELOG 以取得詳細資訊。

建立資料庫帳戶

  1. 從 Azure 入口網站功能表或[首頁] 頁面,選取 [建立資源]。

  2. 在 [新增] 頁面上,搜尋並選取 [Azure Cosmos DB]。

  3. 在 [選取 API 選項] 頁面上,選取 [核心 (SQL) - 建議] 區段中的 [建立] 選項。 Azure Cosmos DB 提供五個 API:Core(SQL) 和 MongoDB (適用於文件資料)、Gremlin (適用於圖形資料)、Azure 資料表及 Cassandra。 目前,您必須為每個 API 建立個別個帳戶。 進一步了解 SQL API

  4. 在 [建立 Azure Cosmos DB 帳戶] 頁面中,輸入新 Azure Cosmos 帳戶的基本設定。

    設定 描述
    訂用帳戶 訂閱名稱 選取要用於此 Azure Cosmos 帳戶的 Azure 訂用帳戶。
    資源群組 資源群組名稱 選取資源群組,或選取 [新建],然後輸入新資源群組的唯一名稱。
    帳戶名稱 唯一的名稱 輸入名稱來識別您的 Azure Cosmos 帳戶。 因為 documents.azure.com 會附加到您所提供的名稱以建立 URI,請使用唯一名稱。

    名稱只能包含小寫字母、數字及連字號 (-) 字元。 其長度必須介於 3 到 44 個字元之間。
    Location 最接近使用者的區域 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。 使用最接近使用者的位置,讓他們能以最快速度存取資料。
    容量模式 佈建輸送量或無伺服器 選取 [佈建的輸送量],以佈建的輸送量模式建立帳戶。 選取 [無伺服器],以無伺服器模式建立帳戶。
    申請 Azure Cosmos DB 免費階層折扣 適用不適用 使用 Azure Cosmos DB 免費層,您將可在帳戶中免費取得前 1000 RU/秒和 25 GB 的儲存體。 深入了解免費層

    注意

    每個 Azure 訂用帳戶最多可以有一個免費層的 Azure Cosmos DB 帳戶,而且必須在建立帳戶時選擇加入。 如果您看不到套用免費層折扣的選項,這表示訂用帳戶中的另一個帳戶已透過免費層啟用。

    The new account page for Azure Cosmos DB

  5. 在 [全域散發] 索引標籤中,設定下列詳細資料。 您可以保留預設值以用於本快速入門:

    設定 說明
    異地備援 停用 藉由將您的區域與配對區域進行配對,在您的帳戶上啟用或停用全域散發。 您可以在稍後將更多區域新增至您的帳戶。
    多區域寫入 停用 多重區域寫入功能可讓您利用在全球為資料庫及容器佈建的輸送量。

    注意

    如果您選取 [無伺服器] 作為容量模式,則無法使用下列選項:

    • 申請免費層折扣
    • 異地備援
    • 多區域寫入
  6. (選用) 您可以在下列索引標籤中設定其他詳細資料:

    • 網路 - 設定從虛擬網路存取
    • 備份原則 - 設定定期連續備份原則。
    • 加密 - 使用服務管理的金鑰或客戶自控金鑰
    • 標籤 - 標籤為成對的名稱和值,可讓您將相同的標籤套用至多個資源與資源群組,以便為資源分類及檢視合併的帳單。
  7. 選取 [檢閱 + 建立]。

  8. 檢閱帳戶設定,然後選取 [建立]。 建立帳戶需要幾分鐘的時間。 等候入口網站頁面顯示 [您的部署已完成] 訊息。

    The Azure portal Notifications pane

  9. 選取 [移至資源] 以移至 Azure Cosmos DB 帳戶頁面。

    The Azure Cosmos DB account page

新增容器

您現在可以在 Azure 入口網站中使用 [資料總管] 工具,建立資料庫和容器。

  1. 選取 [資料總管]>[新增容器]。

    [新增容器] 區域會顯示在最右邊,您可能需要向右捲動才能看到它。

    The Azure portal Data Explorer, Add Container pane

  2. 在 [新增容器] 頁面上,輸入新容器的設定。

    設定 建議的值 描述
    資料庫識別碼 ToDoList 輸入 Tasks 作為新資料庫的名稱。 資料庫名稱必須包含從 1 到 255 個字元,且不能包含 /, \\, #, ? 或尾端空格。 核取 [共用容器間的輸送量] 選項,它可讓您在資料庫上的所有容器內共用佈建到資料庫的輸送量。 此選項也有助於節省成本。
    資料庫輸送量 您可以佈建 [自動調整] 或 [手動] 輸送量。 手動輸送量可讓您自行調整 RU/秒,而自動調整輸送量可讓系統根據使用量來調整 RU/秒。 針對此範例,請選取 [手動]。

    讓輸送量保持在每秒 400 個要求單位 (RU/秒)。 如果您想要降低延遲,稍後可以使用容量計算機來評估所需的 RU/秒,以擴大輸送量。

    注意:在無伺服器帳戶中建立新容器時,無法使用此設定。
    容器識別碼 項目 輸入 Items 作為新容器的名稱。 容器識別碼與資料庫名稱具有相同的字元需求。
    分割區索引鍵 /類別 本文中所述的範例使用 /category 作為分割區索引鍵。

    請勿在此範例中新增唯一索引鍵或開啟分析存放區。 唯一索引鍵可讓您藉由確保每個分割索引鍵有一或多個唯一值,來對資料庫新增一層資料完整性。 如需詳細資訊,請參閱 Azure Cosmos DB 中的唯一索引鍵。分析存放區可用於大規模分析操作資料,而不會對交易式工作負載產生影響。

    選取 [確定]。 [資料總管] 會顯示新的資料庫和容器。

新增範例資料

您現在可以使用 [資料總管] 將資料新增至您的新容器。

  1. 在 [資料總管] 中,展開 Tasks 資料庫,然後展開 Items 容器。 選取 [項目],然後選取 [新增項目]

    Create new documents in Data Explorer in the Azure portal

  2. 現在將文件新增至具有下列結構的容器。

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. 將 json 新增至 [文件] 索引標籤後,選取 [儲存]

    Copy in json data and select Save in Data Explorer in the Azure portal

  4. 多建立並儲存一份文件,以便在其中插入 id 屬性的唯一值,並適當變更其他屬性。 新文件可擁有您想要的任何結構,因為 Azure Cosmos DB 不會對您的資料強加任何結構描述。

查詢資料

您可以在 [資料總管] 中,使用查詢來擷取和篩選您的資料。

  1. 在 [資料總管] 中的 [項目] 索引標籤頂端,檢閱預設查詢 SELECT * FROM c。 此查詢會依照識別碼順序擷取並顯示容器中的所有文件。

    Default query in Data Explorer is SELECT * FROM c

  2. 若要變更查詢,請選取 [編輯篩選條件],以 ORDER BY c._ts DESC 取代預設查詢,然後選取 [套用篩選條件]。

    Change the default query by adding ORDER BY c._ts DESC and clicking Apply Filter

    經過修改的查詢會根據文件的時間戳記,依遞減順序顯示文件,因此現會最先列出您的第二份文件。

    Changed query to ORDER BY c._ts DESC and clicking Apply Filter

若您熟悉 SQL 語法,則可在查詢述詞方塊中輸入任何支援的 SQL 查詢。 您也可以使用 [資料總管] 來建立伺服器端商務邏輯的預存程序、UDF 和觸發程序。

[資料總管] 可讓您透過 Azure 入口網站輕鬆存取 API 中所有可用的內建程式設計資料存取功能。 您也可以使用入口網站來調整輸送量、取得金鑰和連接字串,以及檢閱 Azure Cosmos DB 帳戶的計量和 SLA。

複製範例應用程式

現在,我們將從 GitHub 複製 SQL API 應用程式、設定連接字串,然後加以執行。 本快速入門使用第 4 版的 Python SDK

  1. 開啟命令提示字元,建立名為 git-samples 的新資料夾,然後關閉命令提示字元。

    md git-samples
    

    如果您使用 bash 提示字元,應改為使用下列命令︰

    mkdir "git-samples"
    
  2. 開啟 git 終端機視窗 (例如 git bash),並使用 cd 命令變更至要安裝範例應用程式的新資料夾。

    cd "git-samples"
    
  3. 執行下列命令來複製範例存放庫。 此命令會在您的電腦上建立範例應用程式副本。

    git clone https://github.com/Azure-Samples/azure-cosmos-db-python-getting-started.git
    

更新您的連接字串

現在,返回 Azure 入口網站以取得連接字串資訊,並將它複製到應用程式中。

  1. Azure 入口網站的 Azure Cosmos DB 帳戶中,選取左側導覽列中的 [金鑰]。 在下一個步驟中,使用畫面右側的複製按鈕,將 URI主要金鑰複製到 cosmos_get_started.py 檔案中。

    Get an access key and URI in the Keys settings in the Azure portal

  2. 在 Visual Studio Code 中,開啟 \git-samples\azure-cosmos-db-python-getting-started 中的 cosmos_get_started.py 檔案。

  3. 從入口網站複製您的 URI 值 (使用 [複製] 按鈕),並使其成為 cosmos_get_started.py 中的端點變數值。

    endpoint = 'https://FILLME.documents.azure.com',

  4. 然後,從入口網站複製您的 [主要金鑰] 值,並使其成為 cosmos_get_started.py 中的 [金鑰] 值。 您現已更新應用程式,使其具有與 Azure Cosmos DB 通訊所需的所有資訊。

    key = 'FILLME'

  5. 儲存 cosmos_get_started.py 檔案。

檢閱程式碼

此為選用步驟。 了解以程式碼建立的資料庫資源,或直接跳到更新您的連接字串

下列程式碼片段全部取自 cosmos_get_started.py 檔案。

  • 已初始化 CosmosClient。 請務必如更新連接字串一節所述,更新「端點」和「索引鍵」值。

    client = CosmosClient(endpoint, key)
    
  • 已建立新資料庫。

    database_name = 'AzureSampleFamilyDatabase'
    database = client.create_database_if_not_exists(id=database_name)
    
  • 隨即建立新的容器,其中包含 400 RU/秒的已佈建輸送量。 我們選擇 lastName 作為分割索引鍵,讓我們能進行可對此屬性進行篩選的有效查詢。

    container_name = 'FamilyContainer'
    container = database.create_container_if_not_exists(
        id=container_name, 
        partition_key=PartitionKey(path="/lastName"),
        offer_throughput=400
    )
    
  • 有些項目會新增至容器。 容器是可擁有不同架構的項目 (JSON 文件) 集合。 協助程式方法 get_[name]_family_item 會以 JSON 文件形式,傳回 Azure Cosmos DB 中儲存的系列表示法。

    for family_item in family_items_to_create:
        container.create_item(body=family_item)
    
  • 已使用 read_item 方法執行端點讀取 (索引鍵值查閱)。 我們會列出每個作業的 RU 費用

    for family in family_items_to_create:
        item_response = container.read_item(item=family['id'], partition_key=family['lastName'])
        request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
        print('Read item with id {0}. Operation consumed {1} request units'.format(item_response['id'], (request_charge)))
    
  • 已使用 SQL 查詢語法執行查詢。 因為我們在 WHERE 子句中使用 lastName 的分割索引鍵值,所以 Azure Cosmos DB 會有效地將此查詢路由傳送至相關的分割區,以改善效能。

    query = "SELECT * FROM c WHERE c.lastName IN ('Wakefield', 'Andersen')"
    
    items = list(container.query_items(
        query=query,
        enable_cross_partition_query=True
    ))
    
    request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
    
    print('Query returned {0} items. Operation consumed {1} request units'.format(len(items), request_charge))
    

執行應用程式

  1. 在 Visual Studio Code 中,選取 [檢視]>[命令選擇區]。

  2. 在提示字元中,輸入 Python: Select Interpreter,然後選取要使用的 Python 版本。

    Visual Studio Code 中的頁尾會更新以指出選取的解譯器。

  3. 選取 [檢視]>[整合式終端機] 以開啟 Visual Studio Code 整合式終端機。

  4. 在整合式終端機視窗中,確定您在 azure-cosmos-db-python-getting-started 資料夾中。 如果不是,請執行下列命令來切換至範例資料夾。

    cd "\git-samples\azure-cosmos-db-python-getting-started"`
    
  5. 執行以下命令來安裝 azure-cosmos 套件。

    pip install --pre azure-cosmos
    

    如果您收到有關在嘗試安裝 azure-cosmos 時拒絕存取的錯誤,您必須以系統管理員身分執行 VS Code

  6. 執行下列命令以執行範例,並且在 Azure Cosmos DB 中建立和儲存新文件。

    python cosmos_get_started.py
    
  7. 若要確認已建立並儲存新項目,請在 Azure 入口網站中,選取 [資料總管]>[AzureSampleFamilyDatabase]>[項目]。 檢視已建立的項目。 例如,以下是適用於 Andersen 家族的範例 JSON 文件:

    {
        "id": "Andersen-1569479288379",
        "lastName": "Andersen",
        "district": "WA5",
        "parents": [
            {
                "familyName": null,
                "firstName": "Thomas"
            },
            {
                "familyName": null,
                "firstName": "Mary Kay"
            }
        ],
        "children": null,
        "address": {
            "state": "WA",
            "county": "King",
            "city": "Seattle"
        },
        "registered": true,
        "_rid": "8K5qAIYtZXeBhB4AAAAAAA==",
        "_self": "dbs/8K5qAA==/colls/8K5qAIYtZXc=/docs/8K5qAIYtZXeBhB4AAAAAAA==/",
        "_etag": "\"a3004d78-0000-0800-0000-5d8c5a780000\"",
        "_attachments": "attachments/",
        "_ts": 1569479288
    }
    

在 Azure 入口網站中檢閱 SLA

Azure 入口網站會監視您的 Cosmos DB 帳戶輸送量、儲存體、可用性、延遲和一致性。 與 Azure Cosmos DB 服務等級協定 (SLA) 相關聯的計量圖表會顯示相較於實際效能的 SLA 值。 此計量套件可讓您以更透明的方式監視監視 SLA。

若要檢閱計量和 SLA:

  1. 在您的 Cosmos DB 帳戶導覽功能表中,選取 [計量]

  2. 選取一個索引標籤 (例如 [延遲]),並在右側選取時間範圍。 比較圖表中的實際SLA 的資料行。

    Azure Cosmos DB metrics suite

  3. 檢閱其他索引標籤中的計量。

清除資源

完成您的應用程式和 Azure Cosmos DB 帳戶之後,您可以將建立的 Azure 資源刪除,以免產生更多費用。 若要刪除資源:

  1. 在 Azure 入口網站的 [搜尋] 列中,搜尋並選取 [資源群組]

  2. 在該清單中,選取您在本快速入門中建立的資源群組。

    Select the resource group to delete

  3. 在 [資源群組] 的 [概觀] 頁面中,選取 [刪除資源群組]

    Delete the resource group

  4. 在下個視窗中輸入要刪除的資源群組名稱,然後選取 [刪除]

後續步驟

在本快速入門中,您已了解如何建立 Azure Cosmos DB 帳戶、如何使用 [資料總管] 建立容器,以及如何在 Visual Studio Code 中執行 Python 應用程式。 您現在可以將其他資料匯入 Azure Cosmos DB 帳戶中。

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎? 您可以使用現有資料庫叢集的相關資訊進行容量規劃。