微服務

發行項
03/20/2024

在本教學課程中，您會使用 Azure Cosmos DB for PostgreSQL 作為多個微服務的儲存體後端，以示範這類叢集的範例設定和基本作業。了解如何：

建立叢集
建立微服務的角色
使用 psql 公用程式來建立角色和分散式結構描述
建立範例服務的資料表
設定服務
執行服務
探索資料庫

適用於： Azure Cosmos DB for PostgreSQL (由 PostgreSQL 的 Citus 資料庫延伸模組提供)

必要條件

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

建立叢集

登入 Azure 入口網站，並遵循下列步驟來建立 Azure Cosmos DB for PostgreSQL 叢集：

直接連結
入口網站搜尋

移至 Azure 入口網站中的建立 Azure Cosmos DB for PostgreSQL 叢集。

在 [建立 Azure Cosmos DB for PostgreSQL 叢集] 表單上：

填寫 [基本資料] 索引標籤上的資訊。

大多數選項都一目了然，但請記住：
- 叢集名稱會決定應用程式用來連線的 DNS 名稱，其格式為 <node-qualifier>-<clustername>.<uniqueID>.postgres.cosmos.azure.com。
- 您可以選擇主要 PostgreSQL 版本，例如 15。 Azure Cosmos DB for PostgreSQL 一律支援所選取主要 Postgres 版本的最新 Citus 版本。
- 管理使用者名稱的值必須是 citus。
- 您可以將資料庫名稱保留為其預設值 'citus'，或定義您唯一的資料庫名稱。您無法在叢集佈建之後重新命名資料庫。
選取畫面底部的 [下一步: 網路]。
在 [網路] 畫面上，選取 [允許從 Azure 服務及 Azure 內部資源對此叢集進行公用存取]。
選取 [檢閱 + 建立]，並在驗證通過時選取 [建立] 以建立叢集。
佈建需要幾分鐘的時間。此頁面會重新導向以監視部署。當狀態從 [正在部署] 變更為 [您的部署已完成] 時，選取 [移至資源]。

建立微服務的角色

分散式結構描述可以重新放置於 Azure Cosmos DB for PostgreSQL 叢集內。系統可以在可用節點之間以整個單位的形式來將其重新平衡，以允許有效率地共用資源，而不需要手動配置。

根據設計，微服務擁有其儲存體層，因此我們不會對其所建立和儲存的資料表和資料類型進行任何假設。我們會提供每個服務的結構描述，並假設其使用不同的 ROLE 來連線至資料庫。使用者連線時，其角色名稱會放在 search_path 的開頭，因此如果角色符合結構描述名稱，則您不需要任何應用程式變更，即可設定正確的 search_path。

在我們的範例中，使用三個服務：

使用者
time
ping

請遵循描述如何建立使用者角色的步驟，並為每個服務建立下列角色：

userservice
timeservice
pingservice

使用 psql 公用程式來建立分散式結構描述

使用 psql 連線到 Azure Cosmos DB for PostgreSQL 後，您可以完成一些基本工作。

有兩種方式可以在 Azure Cosmos DB for PostgreSQL 中散發結構描述：

呼叫 citus_schema_distribute(schema_name) 函數，以手動進行：

CREATE SCHEMA AUTHORIZATION userservice;
CREATE SCHEMA AUTHORIZATION timeservice;
CREATE SCHEMA AUTHORIZATION pingservice;

SELECT citus_schema_distribute('userservice');
SELECT citus_schema_distribute('timeservice');
SELECT citus_schema_distribute('pingservice');

此方法也可讓您將現有的一般結構描述轉換成分散式結構描述。

注意

您只能散發未包含分散式和參考資料表的結構描述。

替代方式是啟用 citus.enable_schema_based_sharding 設定變數：

SET citus.enable_schema_based_sharding TO ON;

CREATE SCHEMA AUTHORIZATION userservice;
CREATE SCHEMA AUTHORIZATION timeservice;
CREATE SCHEMA AUTHORIZATION pingservice;

您可以變更目前工作階段的變數，或在協調器節點參數中永久變更。將參數設定為 ON 時，預設會散發所有已建立的結構描述。

您可以執行下列命令來列出目前的分散式結構描述：

select * from citus_schemas;

 schema_name | colocation_id | schema_size | schema_owner
-------------+---------------+-------------+--------------
 userservice |             5 | 0 bytes     | userservice
 timeservice |             6 | 0 bytes     | timeservice
 pingservice |             7 | 0 bytes     | pingservice
(3 rows)

建立範例服務的資料表

您現在需要針對每個微服務連線至 Azure Cosmos DB for PostgreSQL。您可以使用 \c 命令來交換現有 psql 執行個體內的使用者。

\c citus userservice

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL
);

\c citus timeservice

CREATE TABLE query_details (
    id SERIAL PRIMARY KEY,
    ip_address INET NOT NULL,
    query_time TIMESTAMP NOT NULL
);

\c citus pingservice

CREATE TABLE ping_results (
    id SERIAL PRIMARY KEY,
    host VARCHAR(255) NOT NULL,
    result TEXT NOT NULL
);

設定服務

在本教學課程中，我們使用一組簡單的服務。取得方式是複製此公用存放庫：

git clone https://github.com/citusdata/citus-example-microservices.git

$ tree
.
├── LICENSE
├── README.md
├── ping
│   ├── app.py
│   ├── ping.sql
│   └── requirements.txt
├── time
│   ├── app.py
│   ├── requirements.txt
│   └── time.sql
└── user
    ├── app.py
    ├── requirements.txt
    └── user.sql

不過，在執行服務之前，請編輯 user/app.py、ping/app.py 和 time/app.py 檔案，為您的 Azure Cosmos DB for PostgreSQL 叢集提供連線設定：

# Database configuration
db_config = {
    'host': 'c-EXAMPLE.EXAMPLE.postgres.cosmos.azure.com',
    'database': 'citus',
    'password': 'SECRET',
    'user': 'pingservice',
    'port': 5432
}

進行變更之後，請儲存所有修改過的檔案，然後移至執行服務的下一個步驟。

執行服務

切換至每個應用程式目錄，並在其自己的 Python 環境中予以執行。

cd user
pipenv install
pipenv shell
python app.py

針對時間和 Ping 服務重複命令，之後，您就可以使用 API。

建立一些使用者：

curl -X POST -H "Content-Type: application/json" -d '[
  {"name": "John Doe", "email": "john@example.com"},
  {"name": "Jane Smith", "email": "jane@example.com"},
  {"name": "Mike Johnson", "email": "mike@example.com"},
  {"name": "Emily Davis", "email": "emily@example.com"},
  {"name": "David Wilson", "email": "david@example.com"},
  {"name": "Sarah Thompson", "email": "sarah@example.com"},
  {"name": "Alex Miller", "email": "alex@example.com"},
  {"name": "Olivia Anderson", "email": "olivia@example.com"},
  {"name": "Daniel Martin", "email": "daniel@example.com"},
  {"name": "Sophia White", "email": "sophia@example.com"}
]' http://localhost:5000/users

列出已建立的使用者：

curl http://localhost:5000/users

取得目前時間：

Get current time:

針對 example.com，執行 Ping：

curl -X POST -H "Content-Type: application/json" -d '{"host": "example.com"}' http://localhost:5002/ping

探索資料庫

既然您已呼叫一些 API 函數、已儲存資料，而且您可以檢查 citus_schemas 是否反映預期內容：

select * from citus_schemas;

 schema_name | colocation_id | schema_size | schema_owner
-------------+---------------+-------------+--------------
 userservice |             1 | 112 kB      | userservice
 timeservice |             2 | 32 kB       | timeservice
 pingservice |             3 | 32 kB       | pingservice
(3 rows)

當您已建立結構描述時，未將要建立結構描述的機器告知 Azure Cosmos DB for PostgreSQL。這會自動完成。您可以使用下列查詢來查看每個結構描述所在的位置：

  select nodename,nodeport, table_name, pg_size_pretty(sum(shard_size))
    from citus_shards
group by nodename,nodeport, table_name;

nodename  | nodeport |         table_name         | pg_size_pretty
-----------+----------+---------------------------+----------------
 localhost |     9701 | timeservice.query_details | 32 kB
 localhost |     9702 | userservice.users         | 112 kB
 localhost |     9702 | pingservice.ping_results  | 32 kB

為求此頁面上範例輸出的簡潔性，而不使用 nodename (如 Azure Cosmos DB for PostgreSQL 中所顯示)，我們會將其取代為 localhost。假設 localhost:9701 是背景工作角色 1，而 localhost:9702 是背景工作角色 2。受控服務上的節點名稱較長，而且包含隨機化元素。

您可以看到時間服務落在節點 localhost:9701，而使用者和 Ping 服務共用第二個背景工作角色 localhost:9702 上的空間。範例應用程式十分簡單，而且此處的資料大小可予以忽略，但假設您因節點之間的儲存體空間使用率不平均而煩惱。讓兩個較小的時間和 Ping 服務位於一部機器，而讓大型使用者服務則單獨位於一部機器，這更有意義。

您可以輕鬆地依磁碟大小重新平衡叢集：

select citus_rebalance_start();

NOTICE:  Scheduled 1 moves as job 1
DETAIL:  Rebalance scheduled as background job
HINT:  To monitor progress, run: SELECT * FROM citus_rebalance_status();
 citus_rebalance_start
-----------------------
                     1
(1 row)

完成時，您可以檢查我們的新版面配置外觀：

  select nodename,nodeport, table_name, pg_size_pretty(sum(shard_size))
    from citus_shards
group by nodename,nodeport, table_name;

 nodename  | nodeport |         table_name        | pg_size_pretty
-----------+----------+---------------------------+----------------
 localhost |     9701 | timeservice.query_details | 32 kB
 localhost |     9701 | pingservice.ping_results  | 32 kB
 localhost |     9702 | userservice.users         | 112 kB
(3 rows)

根據預期，已移動結構描述，而且我們有一個更平衡的叢集。此作業對應用程式而言是透明的。您甚至不需要將它們重新啟動，它們會繼續提供查詢。

下一步

在本教學課程中，您已了解如何建立分散式結構描述，以及將其用作儲存體來執行微服務。您也了解如何探索和管理結構描述型分區化 Azure Cosmos DB for PostgreSQL。

了解叢集節點類型

微服務