グローバルクラスターへの接続
グローバルクラスターが実行されたら、エンドポイントと認証トークンを使用して接続します。このページでは、2つのエンドポイントタイプ、それぞれの使用場面、およびスイッチオーバーとフェイルオーバー時のルーティング動作について説明します。
この機能は、Business Critical（SaaS）および BYOC デプロイでのみ利用できます。
この機能は、すべての AWS リージョンと、Google Cloud の gcp-us-central1 および gcp-us-east4 リージョンで利用できます。Microsoft Azure では利用できません。
エンドポイントタイプの選択
グローバルクラスターは、2つの接続方法を提供します。
-
グローバルエンドポイント経由
-
グローバルクラスター内のプライマリークラスターまたはセカンダリークラスターのパブリックまたはプライベートエンドポイント経由
次の表は、2つの接続エンドポイントを比較しています。
グローバルエンドポイント | プライマリークラスターまたはセカンダリークラスターのエンドポイント | |
|---|---|---|
書き込みルーティング | プライマリークラスターに自動的にルーティング | プライマリーのパブリックエンドポイントのみが書き込みを受け付ける |
読み込みルーティング | プライマリークラスターにルーティング （レイテンシーに基づく最も近い利用可能なクラスターへのインテリジェントルーティングは、近日対応予定です。） | 接続した特定のクラスターに読み込みが行われる |
スイッチオーバー / フェイルオーバー | 自動的に再ルーティング — コード変更は不要 | 新しいプライマリーを指すように接続を更新する必要がある |
プライベートリンク | 非対応（パブリックインターネットが必要） | 対応 |
最適な用途 | 自動フェイルオーバーとレイテンシーベースのルーティングが必要な本番アプリケーション | 特定のクラスターへの直接アクセス（例：環境レプリケーション、テスト、デバッグ） |
本番ワークロードにはグローバルエンドポイントの使用を推奨します。これにより、スイッチオーバーまたはフェイルオーバー時にアプリケーションコードでエンドポイントの変更を処理する必要がなくなります。
エンドポイントとトークンの取得
グローバルクラスターまたは対象のクラスターに移動します。
-
グローバルエンドポイントの場合：グローバルクラスターページに移動します。
-
パブリックエンドポイントの場合：特定のプライマリークラスターまたはセカンダリークラスターのクラスター詳細ページに移動します。
Connect カードで、グローバルエンドポイントまたはパブリックエンドポイントをコピーします。
グローバルエンドポイントを使用した接続
グローバルエンドポイントは、グローバルクラスター内の現在のプライマリークラスターに常にリクエストをルーティングする単一の URL です。
スイッチオーバーまたはフェイルオーバーが発生すると、Zilliz Cloud はグローバルエンドポイントが新しいプライマリークラスターを指すように自動更新します。そのため、アプリケーションはクラスター URI を手動で変更することなく、同じエンドポイントを引き続き使用できます。
Zilliz Cloud は、SDK と RESTful API の両方によるグローバルエンドポイントへの接続をサポートしています。本番アプリケーションでは SDK クライアントの使用を推奨します。
RESTful API 接続より SDK 接続が推奨される理由
SDK クライアントは、エンドポイント一覧、プライマリーとセカンダリーの役割、クラスターの健全性など、グローバルクラスターのトポロジーを取得できます。この情報により、プライマリークラスターが変更されたときに、SDK クライアントはより迅速に対応できます。また将来的には、書き込みリクエストをプライマリークラスターへ、対象となる読み取りリクエストをグローバルクラスタートポロジーに基づいてルーティングする読み書き分離もサポートする予定です。
一方、RESTful API 接続はグローバルクラスタートポロジー情報を保持しません。そのため、スイッチオーバーまたはフェイルオーバー後に新しいプライマリークラスターへ切り替わるまで、より長い時間がかかる場合があります。同じ理由により、RESTful API 接続は読み書き分離をサポートできません。
次の表は、SDK 接続と RESTful API 接続を比較しています。
比較項目 | SDK 接続 | RESTful API 接続 |
|---|---|---|
最適な用途 | 役割変更時の迅速な復旧と、将来の読み書き分離を必要とする本番アプリケーション。 | 軽量スクリプト、単純な REST 統合、単発の管理操作。 |
トポロジー認識 | エンドポイント一覧、プライマリーとセカンダリーの役割、クラスターの健全性など、グローバルクラスタートポロジーを取得します。 | グローバルクラスタートポロジー情報を保持しません。 |
プライマリー変更への対応 | スイッチオーバーまたはフェイルオーバー後にプライマリークラスターが変更されると、通常は数秒以内に迅速に対応できます。 | クライアントがトポロジー情報を保持しないため、新しいプライマリーへの切り替えに通常は数分かかる場合があります。 |
読み書き分離 | ✅ 近日対応予定です。 | ❌ 非対応 |
SDK バージョンの確認
開始する前に、SDK がインストールされており、最低バージョン要件を満たしていることを確認してください。
SDK | 最低バージョン |
|---|---|
Python |
|
Java |
|
接続ガイド
- Python
- Java
- cURL
from pymilvus import MilvusClient
# Use the global endpoint for automatic routing
client = MilvusClient(
uri="YOUR_GLOBAL_ENDPOINT", # Global endpoint from the console
token="YOUR_CLUSTER_TOKEN" # API key or username:password
)
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.client.ConnectConfig;
// Use the global endpoint for automatic routing
ConnectConfig connectConfig = ConnectConfig.builder()
.uri("YOUR_GLOBAL_ENDPOINT") // Global endpoint from the console
.token("YOUR_CLUSTER_TOKEN") // API key or username:password
.build();
MilvusClientV2 client = new MilvusClientV2(connectConfig);
curl --request POST \
--url "YOUR_GLOBAL_ENDPOINT" \
--header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
--header "Content-Type: application/json" \
パブリックエンドポイントを使用した接続
グローバルクラスター内の各クラスターには、それぞれ独自のパブリックエンドポイントがあります。特定のクラスターを直接ターゲットにする必要がある場合は、これを使用してください。
- Python
- Java
- NodeJS
- Go
- cURL
from pymilvus import MilvusClient
# Connect directly to a specific cluster
client = MilvusClient(
uri="YOUR_CLUSTER_PUBLIC_ENDPOINT", # Public endpoint of a specific cluster
token="YOUR_CLUSTER_TOKEN" # API key or username:password
)
import io.milvus.v2.client.MilvusClientV2;
import io.milvus.v2.client.ConnectConfig;
// Connect directly to a specific cluster
ConnectConfig connectConfig = ConnectConfig.builder()
.uri("YOUR_CLUSTER_PUBLIC_ENDPOINT") // Public endpoint of a specific cluster
.token("YOUR_CLUSTER_TOKEN") // API key or username:password
.build();
MilvusClientV2 client = new MilvusClientV2(connectConfig);
const { MilvusClient } = require("@zilliz/milvus2-sdk-node")
// Connect directly to a specific cluster
const client = new MilvusClient({
address: "YOUR_CLUSTER_PUBLIC_ENDPOINT", // Public endpoint of a specific cluster
token: "YOUR_CLUSTER_TOKEN" // API key or username:password
})
import "github.com/milvus-io/milvus/client/v2/milvusclient"
// Connect directly to a specific cluster
client, err := milvusclient.New(ctx, &milvusclient.ClientConfig{
Address: "YOUR_CLUSTER_PUBLIC_ENDPOINT", // Public endpoint of a specific cluster
APIKey: "YOUR_CLUSTER_TOKEN", // API key or username:password
})
curl --request POST \
--url "YOUR_CLUSTER_PUBLIC_ENDPOINT" \
--header "Authorization: Bearer YOUR_CLUSTER_TOKEN" \
--header "Content-Type: application/json" \
パブリックエンドポイントを使用する場合、書き込み操作を受け付けるのはプライマリークラスターのパブリックエンドポイントのみです。セカンダリークラスターのパブリックエンドポイントへの書き込みは失敗します。
ルーティング動作
通常運用時
リクエストタイプ | グローバルエンドポイント | パブリックエンドポイント |
|---|---|---|
書き込み（insert、upsert、delete） | プライマリークラスターにルーティング | プライマリークラスターのエンドポイントでのみ受け付ける |
読み取り（search、query） | プライマリークラスターにルーティング （レイテンシーに基づいて最も近い利用可能なクラスターへルーティングする機能は近日対応予定です。） | 接続先の特定のクラスターが処理 |
スイッチオーバー / フェイルオーバー中および完了後
シナリオ | グローバルエンドポイント | パブリックエンドポイント |
|---|---|---|
スイッチオーバー実行中 | 書き込みは短時間停止した後、新しいプライマリーで再開します。読み取りは継続します。 | エンドポイントは変更されません。以前のプライマリーはセカンダリーになります。 |
フェイルオーバー実行中 | 新しいプライマリーが昇格するまで書き込みは利用できません。読み取りはセカンダリーで継続します。 | 以前のプライマリーのエンドポイントには接続できなくなります。 |
完了後 | 新しいプライマリーに自動的にルーティングされます。コード変更は不要です。 | 書き込みには新しいプライマリーのパブリックエンドポイントを使用するようコードを更新します。 |
SDK の自動再接続
グローバルエンドポイントを使用する場合、Zilliz Cloud SDK はスイッチオーバーおよびフェイルオーバー中のエンドポイントの再ルーティングを処理します。アプリケーション側でルーティング変更に対するリトライロジックを実装する必要はありません。ただし、切り替え時点で進行中の書き込みは一時的なエラーを受ける可能性があります。これらのケースは、アプリケーション内の標準的なリトライロジックで処理されます。