ScalarDB Cluster gRPC API ガ イド
このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。
このドキュメントでは、ScalarDB Cluster gRPC API について説明します。
ScalarDB Cluster を使用するには、ライセンスキー (試用ライセンスまたは商用ライセンス) が必要です。ライセンスキーをお持ちでない場合は、お問い合わせください。
ScalarDB Cluster は、内部で gRPC API を使用する Java API を提供します。
Java または JVM 言語を使用する場合は、ScalarDB Cluster gRPC API を直接使用する代わりに、Java API を使用できます。
Java API の詳細については、Java API を使用した ScalarDB Cluster の開発者ガイドを参照してください。
ScalarDB Cluster gRPC API のサービスとメッセージの詳細については、scalardb-cluster.proto ファイルの定義を参照してください。商用ライセンスを持つ ScalarDB Cluster ユーザーで、scalardb-cluster.proto ファイルが必要な場合は、お問い合わせください。
ScalarDB Cluster gRPC API は、次のサービスで構成されています。
scalardb.cluster.rpc.v1.DistributedTransaction: ScalarDB Cluster に分散トランザクション機能を提供します。scalardb.cluster.rpc.v1.TwoPhaseCommitTransaction: ScalarDB Cluster に2フェーズコミットトランザクション機能を提供します。scalardb.cluster.rpc.v1.DistributedTransactionAdmin: 包括的な管理操作を提供します。
次のセクションでは、各サービスの使用方法について説明します。
ScalarDB Cluster gRPC API でのエラー処理の概要
各サービスの使用方法を説明する前に、このセクションで は ScalarDB Cluster gRPC API でのエラー処理の仕組みについて説明します。
ScalarDB Cluster gRPC API は、エラー処理に Richer error model を採用しています。このモデルにより、サーバーは1つ以上の protobuf メッセージとして表現される追加のエラー詳細を返すことができ、クライアントはそれを利用できるようになります。ScalarDB Cluster gRPC API は、standard set of error message types の1つである google.rpc.ErrorInfo を使用し、追加のエラー詳細を ErrorInfo フィールドに格納します。
ErrorInfo には次のフィールドがあります:
reason: エラーの簡単な説明を提供する文字列。次のセクションでは、各サービスにおけるreasonの可能な値について説明します。domain: エラーの原因を示す文字列。ScalarDB Cluster gRPC API では、この文字列は常にcom.scalar.db.clusterに設定されます。metadata: 特定のエラーのメタデータのマップ。ScalarDB Cluster gRPC API では、エラーがトランザクションに関連している場合、マップにtransactionIdキーを持つトランザクション ID が配置されます。
エラーが発生した場合は、gRPC レスポンスの google.rpc.Status から ErrorInfo を取得できますが、取得方法はプログラミング言語によって異なります。
特定のプログラミング言語で ErrorInfo を取得する方法については、適切なドキュメントを参照して ください。
DistributedTransaction サービスの使用方法
DistributedTransaction サービスは次の RPC を提供します:
Begin: トランザクションを開始します。Get: レコードを取得します。Scan: レコードをスキャンします。Put: レコードを配置します。Delete: レコードを削除します。Mutate複数のレコードを変更 (配置および削除) します。Commit: トランザクションをコミットします。Rollback: トランザクションをロールバックします。
まず、Begin を呼び出してトランザクションを開始します。
次に、Get と Scan を呼び出してレコードを読み取り、Put と Mutate を呼び出してレコードを書き込み、Delete と Mutate を呼び出してレコードを削除します。
トランザクションを終了するには、Commit を呼び出します。あるいは、トランザクションがコミットされる前にいつでも Rollback を呼び出してキャンセルできます。Begin を呼び出すと、応答でトランザクション ID を受け取ります。これを使用して、Get、Scan、Put、Delete、Mutate、Commit、および Rollback を呼び出すことができます。
Begin を呼び出すときに、オプションでトランザクション ID を指定できます。トランザクション ID を指定する場合、ユーザーは ID の一意性を保証する責任があります。トランザクション ID を指定しない場合は、ScalarDB Cluster がトランザクションのトランザクション ID を生成します。
RPC リクエストごとに RequestHeader を設定する必要があります。RequestHeader には、リクエストのホップ数を制限している hop_limit フィールドが含まれています。hop_limit の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、hop_limit は1つ減少します。hop_limit が0に達すると、リクエストは拒否されます。
エラー処理
以下の表は、DistributedTransaction サービスの各 RPC におけるステータスコードと ErrorInfo の reason の可能な値を示しています。
| RPC | ステータスコード | ErrorInfo の reason | 説明 |
|---|---|---|---|
| Begin | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Begin | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Begin | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティ ング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 |
| Begin | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
| Get, Scan, Put, Delete, Mutate | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Get, Scan, Put, Delete, Mutate | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 |
| Get, Scan, Put, Delete, Mutate | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 |
| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 |
| Get, Scan, Put, Delete, Mutate | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
| Put, Delete, Mutate | FAILED_PRECONDITION | UNSATISFIED_CONDITION | 突然変異条件が満たされていません。 |
| Commit | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Commit | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Commit | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 |
| Commit | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 |
| Commit | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 |
| Commit | INTERNAL | UNKNOWN_TRANSACTION_STATUS | トランザクションのステータスは不明です (トランザクションが正常にコミットされたかどうかは不明です)。この状況では、トランザクションが正常にコミットされたかどうかを確認し、そうでない場合は再試行する必要があります。トランザクションステータスを判別する責任はユーザーにあります。トランザクションステータステーブルを作成し、他のアプリケーションデータと連動して更新すると、テーブル自体からトランザクションのステータスを判別できるため、便利です。 |
| Commit | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
| Rollback | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Rollback | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Rollback | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 |
| Rollback | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 |
| Rollback | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
エラーが発生した場合は、Begin の場合を除き、トランザクションをロールバックする必要があります。その後、再試行によって解決できるエラーについては、トランザクションを最初から再試行できます。
上記のエラーの他に、gRPC ライブラリによって返されるエラーが発生する場合があります。これらの場合、応答には ErrorInfo は含まれません。詳細については、gRPC ドキュメントを参照してください。
gRPC では、RPC ごとに期限を設定できます。期限を超えると、DEADLINE_EXCEEDED エラーが表示されます。一般に、RPC が Begin または Commit でない限り、この状況ではトランザクションをロールバックする必要があります。Commit の場合は UNKNOWN_TRANSACTION_STATUS (トランザクションが正常にコミットされたかどうか不明) と同等の状況となり、同様にエラーを処理する必要があります。
TwoPhaseCommitTransaction サービスの使用方法
TwoPhaseCommitTransaction サービスは次の RPC を提供します:
Begin: トランザクションを開始します。Join: トランザクションに参加します。Get: レコードを取得します。Scan: レコードをスキャンします。Put: レコードを配置します。Delete: レコードを削除します。Mutate: 複数のレコードを変更 (配置および削除) します。Prepare: トランザクションを準備します。Validate: トランザクションを検証します。Commit: トランザクションをコミットします。Rollback: トランザクションをロールバックします。
まず、コーディネータープロセスの場合は、Begin を呼び出してトランザクションを開始します。あるいは、参加プロセスの場合は、Join を呼び出して、コーディネーターがすでに開始しているトランザクションに参加できます。次に、Get と Scan を呼び出してレコードを読み取り、Put と Mutate を呼び出してレコードを書き込み、Delete と Mutate を呼び出してレコードを削除できます。トランザクションを確定するには、Prepare、Validate、Commit の順に呼び出します。または、トランザクションがコミットされる前であればいつでも Rollback を呼び出してトランザクションをキャンセルできます。Begin または Join を呼び出すと、応答でトランザクション ID が返されます。これを使用して、Get、Scan、Put、Delete、Mutate、Prepare、Validate、Commit、Rollback を呼び出すことができます。
Begin を呼び出すときに、オプションでトランザクション ID を指定できます。トランザクション ID を指定する場合、ID の一意性を保証するのはユーザーの責任です。トランザクション ID を指定しない場合、ScalarDB Cluster はトランザクションのトランザクション ID を生成します。
RPC リクエストごとに RequestHeader を設定する必要があります。RequestHeader には、リクエストのホップ数を制限している hop_limit フィールドが含まれています。hop_limit の目的は、クラスター内での無限ループを防ぐことです。リクエストが別のクラスターノードに転送されるたびに、hop_limit は1つ減ります。hop_limit が0に達すると、リクエストは拒否されます。
エラー処理
次の表は、TwoPhaseCommitTransaction サービスの各 RPC のステータスコードと ErrorInfo の reason の可能な値を示しています。
| RPC | ステータスコード | ErrorInfo の reason | 説明 |
|--------------------------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Begin, Join | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Begin, Join | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Begin, Join | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 |
| Begin, Join | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
| Get, Scan, Put, Delete, Mutate | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Get, Scan, Put, Delete, Mutate | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。これは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 |
| Get, Scan, Put, Delete, Mutate | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 |
| Get, Scan, Put, Delete, Mutate | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 |
| Get, Scan, Put, Delete, Mutate | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
| Put, Delete, Mutate | FAILED_PRECONDITION | UNSATISFIED_CONDITION | 突然変異条件が満たされていません。 |
| Prepare, Validate | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Prepare, Validate | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Prepare, Validate | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 |
| Prepare, Validate | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 |
| Prepare, Validate | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 |
| Prepare, Validate | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
| Commit | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Commit | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Commit | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。このエラーは、トランザクションの有効期限が切れたか、クラスタートポロジの変更によりルーティング情報が更新されたことを示します。この場合は、トランザクションを最初から再試行してください。 |
| Commit | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。これは、クラスターノード間のルーティング情報が矛盾している場合に発生します。通常、このエラーは短時間で解決されるため、このエラーが発生してからしばらく経ってから、トランザクションを最初から再試行できます。 |
| Commit | FAILED_PRECONDITION | TRANSACTION_CONFLICT | トランザクションの競合が発生しました。このエラーが発生した場合は、トランザクションを最初から再試行してください。 |
| Commit | INTERNAL | UNKNOWN_TRANSACTION_STATUS | トランザクションのステータスは不明です (トランザクションが正常にコミットされたかどうかは不明です)。この状況では、トランザクションが正常にコミットされたかどうかを確認し、そうでない場合は再試行する必要があります。トランザクションステータスを判別する責任はユーザーにあります。トランザクションステータステーブルを作成し、他のアプリケーションデータと連動して更新すると、テーブル自体からトランザクションのステータスを判別できるため、便利です。 |
| Commit | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
| Rollback | INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| Rollback | FAILED_PRECONDITION | ILLEGAL_STATE | RPC が無効な状態で呼び出されました。 |
| Rollback | NOT_FOUND | TRANSACTION_NOT_FOUND | 指定されたトランザクション ID に関連付けられたトランザクションが見つかりませんでした。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 |
| Rollback | INTERNAL | HOP_LIMIT_EXCEEDED | ホップ制限を超えました。ロールバックの場合、トランザクションは自動的に期限切れになるため、トランザクションを再試行する必要はありません。 |
| Rollback | INTERNAL | INTERNAL_ERROR | 一時的または非一時的障害のため、操作が失敗しました。トランザクションを最初から再試行することはできますが、原因が非一時的である場合、トランザクションは失敗する可能性があります。 |
エラーが発生した場合は、Begin または Join の場合を除き、トランザクションをロールバックする必要があります。その後、再試行によって解決できるエラーについては、トランザクションを最初から再試行できます。
上記のエラーの他に、gRPC ライブラリによって返されるエラーが発生する場合があります。これらの場合、応答には ErrorInfo は含まれません。詳細については、gRPC ドキュメントを参照してください。
gRPC では、各 RPC に期限を設定できます。期限を超えると、DEADLINE_EXCEEDED エラーが表示されます。一般に、RPC が Begin、Join、または Commit でない限り、この状況ではトランザクションをロールバックする必要があります。Commit の場合、状況は UNKNOWN_TRANSACTION_STATUS (トランザクションが正常にコミットされたかどうか不明) と同等であり、同じ方法でエラーを処理する必要があります。
DistributedTransactionAdmin サービスの使用方法
DistributedTransactionAdmin サービスは、次の RPC を提供します。
CreateNamespace: 名前空間を作成します。DropNamespace: 名前空間を削除します。NamespaceExists: 指定された名前空間が存在するかどうかを返します。CreateTable: テーブルを作成します。DropTable: テーブルを削除します。TruncateTable: テーブルを切り捨てます。TableExists: 指定されたテーブルが存在するかどうかを返します。CreateIndex: インデックスを作成します。DropIndex: インデックスを削除します。IndexExists: 指定されたインデックスが存在するかどうかを返します。RepairNamespace: 不明な状態にある可能性がある名前空間を修復します。RepairTable: 不明な状態にある可能性がある名前空間を修復します。AddNewColumnToTable: テーブルに新しい列を追加します。CreateCoordinatorTables: Coordinator テーブルを作成します。DropCoordinatorTables: Coordinator テーブルを削除します。TruncateCoordinatorTables: Coordinator テーブルを切り捨てます。CoordinatorTablesExist: Coordinator テーブルが存在するかどうかを返します。RepairCoordinatorTables: Coordinator テーブルを修復します。GetTableMetadata: 指定されたテーブルのテーブルメタデータを返します。GetNamespaceTableNames: 指定された名前空間内のテーブルを返します。GetNamespaceNames: ScalarDB によって作成された既存の名前空間名を返します。ImportTable: ScalarDB によって管理されていない既存のテーブルをインポートします。Upgrade: ScalarDB 環境をアップグレードして、最新バージョ ンの ScalarDB API をサポートします。
エラー処理
以下の表は、DistributedTransactionAdmin サービスのすべての RPC のステータスコードと ErrorInfo の reason の可能な値を示しています。
| ステータスコード | ErrorInfo の reason | 説明 |
|---|---|---|
| INVALID_ARGUMENT | ILLEGAL_ARGUMENT | 要求メッセージ内の引数が無効です。 |
| FAILED_PRECONDITION | ILLEGAL_STATE | が無効な状態で呼び出されました。 |
| INTERNAL | INTERNAL_ERROR | 操作が失敗しました。 |
上記のエラー以外にも、gRPC ライブラリによって返されるエラーが発生する場合があります。このような場合、応答には ErrorInfo は含まれません。詳細については、gRPC ドキュメントを参照してください。