YugabyteDB Anywhere REST API

このスキルは、YBA コントロールプレーン REST API をカバーしています。これは、自己管理型 YugabyteDB Anywhere (YBA) インスタンスによって公開される HTTP API で、プロバイダー、リリース、ユニバース、バックアップ、KMS、アラート、HA、RBAC、DR を管理するために使用されます。

対象外:

• YugabyteDB Aeon — フルマネージドクラウド DBaaS で、異なる API サーフェスです。
• YSQL / YCQL — ポート 5433 / 9042 上のデータベース API（PostgreSQL および Cassandra 互換）です。

リファレンス資料:

• 概要: https://docs.yugabyte.com/stable/yugabyte-platform/anywhere-automation/anywhere-api/
• インタラクティブリファレンス: https://api-docs.yugabyte.com/docs/yugabyte-platform/f10502c9c9623-yugabyte-db-anywhere-api-overview
• v1 エンドポイントレジストリ（Play routes）: https://github.com/yugabyte/yugabyte-db/blob/master/managed/src/main/resources/v1.routes
• v2 OpenAPI 仕様: https://github.com/yugabyte/yugabyte-db/tree/master/managed/src/main/resources/openapi（エントリポイント: paths/_index.yaml）

このスキルに含まれるもの:

• references/python-client.md — 最小限の Python ラッパー（yba_request）とスプラット形式の使用法です。Python コードを記述または生成する際に参照してください。
• references/powershell-client.md — powershell-yba モジュールを必要としない単独の PowerShell ラッパー（Invoke-YbaRequest、Get-YbaApiToken、Register-YbaInstance、Get-YbaCustomerId）です。ユーザーが PowerShell を使用しているか、Python が利用できない場合に参照してください。
• references/recipes.md — レジスター/ログイン、プロバイダー、リリース、v1 および v2 ユニバース作成（クラウドおよび Kubernetes）、ストレージ設定（HTTPS プロキシを使用したマルチリージョン S3 を含む）、テレメトリプロバイダー、ユニバースのヘルスチェックとアラート、すべてのスコープでのランタイム設定、バックアップ/復元、非同期タスクの具体的なリクエスト/レスポンス形式です。不慣れなリクエストを作成する際に参照してください。
• references/prometheus.md — YBA にバンドルされた Prometheus インスタンスをポート 9090 でクエリしてユニバースメトリクス（YCQL/YSQL オペレーション/秒、レイテンシーヒストグラム、Kubernetes 上のコンテナ CPU/メモリ、クラウド上のノードエクスポーター CPU、タブレットリーダーバランス、xCluster ラグ）を取得します。Python および PowerShell ヘルパーと、ユニバース API レスポンスから派生した node_prefix / ポッド正規表現が含まれます。ユーザーがメトリクス、ダッシュボード、チャートを求める場合に参照してください。

v1 対 v2

YBA は 2 つの API バージョンを並行して公開しています。両方とも同じホストの /api/ 下にマウントされ、同じ X-AUTH-YW-API-TOKEN ヘッダーを共有しています。

	v1（/api/v1/...）	v2（/api/v2/...）
カバレッジ	包括的 — すべての YBA 機能がここで利用可能です。	部分的で拡大中。 当初はユニバース、アップグレード、RBAC、リリース、テレメトリに焦点を当てています。
リクエスト/レスポンスモデル	内部 Java/Play モデルに密結合 — オプションフィールドが多い、ネストが深い、サーバーが入力するフィールド、廃止予定のアーティファクト。	分離され、手作成された OpenAPI スキーマ — より単純でフラットな形状。送信内容は保存内容にきれいにマッピングされます。
定義ソース	managed/src/main/resources/v1.routes（Play routes ファイル）	managed/src/main/resources/openapi/（OpenAPI 3）
バージョニング	安定。古いエンドポイントは保持されますが、廃止予定とマークされることがあります。	エンドポイントは x-yba-api-visibility（preview、beta、stable、deprecated）と x-yba-api-since を持っています。
優先される場合	v2 にまだ存在しないもの（ほとんどのプロバイダー、KMS、HA、アラート、ランタイム設定）。	存在する新しいユニバース作成/編集/アップグレードフロー — ペイロードがはるかに小さいです。

デフォルトルール: エンドポイントが存在する場合は v2 を優先し、他のすべてについては v1 にフォールバックします。両方を同じスクリプトと同じトークンに対して使用できます。

認証

すべての認証されたリクエストは単一のヘッダーを使用します:

X-AUTH-YW-API-TOKEN: <api-token>
Accept: application/json
Content-Type: application/json

API トークンを取得する方法は 3 つあります。当てはまる最初のものを選択してください。

1. 以前に取得したトークンを再利用する

トークンは期限切れにならず — 明示的にローテーションされるまで有効なままです。ユーザーが既に持っている場合は、直接使用してください。ログしないでください。パスワードのように扱ってください。一般的なストレージ:

export YBA_URL=https://yba.example.com
export YBA_TOKEN=...        # echo しない、コミットしない
export YBA_CUSTOMER_ID=...  # オプション、検索可能（下記参照）

2. メール + パスワードでログイン（既存インスタンス）

POST /api/v1/api_login
{"email": "<email>", "password": "<password>"}

戻り値:

{"apiToken": "...", "apiTokenVersion": 2, "customerUUID": "...", "userUUID": "..."}

このログインは API トークンをローテーションすることに注意してください — このユーザーに対して以前に発行されたトークンは無効になります。再度ログインせずに明示的にローテーションするには、PUT /api/v1/customers/{cUUID}/api_token を使用してください。

3. 新しいインスタンスを登録する

新しくプロビジョニングされた YBA にはユーザーがいません。最初の呼び出しは次のようにする必要があります:

POST /api/v1/register?generateApiToken=1
{"code": "dev|stg|prd", "name": "<full name>", "email": "<email>", "password": "<password>"}

これにより、最初のカスタマー（テナント）と管理者ユーザーが作成され、ログインと同じ {apiToken, customerUUID, userUUID, ...} の形状が返されます。その後の登録試行は cannot register multiple accounts を返します — ログインにフォールバックして処理してください。

カスタマー（テナント）ID

ほぼすべてのエンドポイントはカスタマー / テナントにスコープされています: /api/v1/customers/{cUUID}/...。現在、YBA はインスタンスごとに事実上シングルテナントであるため、この UUID はインスタンスの有効期間中は一定です。

GET /api/v1/customers   →   [{"uuid": "...", "code": "...", "name": "..."}]

一度検索してセッションにキャッシュしてください。 references/python-client.md の Python ラッパーは、ベース URL でキー付けされたモジュールレベルの辞書でこれを実行します。

非同期タスク

多くのステート変更エンドポイント（ユニバース作成、ユニバース編集、ソフトウェアアップグレード、プロバイダー作成、バックアップ取得、...）は、タスクハンドルを持つ形で直ちに返されます:

{"taskUUID": "f3...", "resourceUUID": "..."}

タスクが終了するまでポーリングします:

GET /api/v1/customers/{cUUID}/tasks/{taskUUID}

以下のいずれかが真である場合、タスクは完了しています:

• percent == 100 → 成功
• status が Aborted、Failure のいずれか → 失敗（失敗したサブステップについて details.taskDetails[*] を読んでください）

推奨ポーリング: 5 〜 10 秒ごとで、ほとんどのユニバース操作では 10 分の全体的なタイムアウト（ソフトウェアアップグレードまたは大規模なバックアップではより長い）。taskUUID フィールドが存在しないことを同期レスポンスとして扱ってください — 直接返してください。

エンドポイント発見

2 つの信頼できるソース（この順序で）:

1. インタラクティブリファレンス at https://api-docs.yugabyte.com/docs/yugabyte-platform/ — 読みやすく、リクエスト/レスポンス例があり、タグでフィルタリングできます。
2. リポジトリ内の信頼のソース — ドキュメントが古いときや正確なフィールド名が必要な場合に使用します:
   • v1: v1.routes ファイルでリソース（例：universes、providers、ybdb_release、customer_tasks）を検索します。各行は METHOD path controller.method(...) です。
   • v2: openapi/paths/_index.yaml を検索してください — リソースごとのパスファイルを含むエントリポイント。スキーマは openapi/components/schemas/ の下にあります。

「YBA API を使用して X を実行する」と言われたら、推測する代わりに最初にリソース名についてroutes ファイルを grep してください。

一般的なパラメータ（チートシート）

これら 4 つはすべてのリクエストで一緒に移動します。Python ラッパーのすべてのヘルパーと PowerShell のすべての関数は、それらを 1 つの単位として受け取ります。

パラメータ	注釈
base_url	例：https://yba.example.com — 末尾に /api は不要です。
api_token	X-AUTH-YW-API-TOKEN として送信されます。
customer_id	base_url ごとに一度検索してキャッシュされます。
verify_certificate	プライベート CA 上の YBA インストールは一般的です — これを False に設定する準備をしてください。false の場合は、urllib3 警告も抑制してください。

Python: 最小限のトークン使用

リクエストコードを小さく保ち、AI アシスタントがパイプラインではなくペイロードにトークンを費やすようにします。完全なラッパーは references/python-client.md にあります。最低限必要なものは:

import requests, time, urllib3

def yba_request(base_url, endpoint, token, *, customer_id=None, method="GET",
                payload=None, params=None, verify=True, wait=False, wait_timeout=600):
    if not verify: urllib3.disable_warnings()
    h = {"Accept": "application/json", "Content-Type": "application/json",
         "X-AUTH-YW-API-TOKEN": token}
    url = f"{base_url.rstrip('/')}/{endpoint.lstrip('/')}"
    r = requests.request(method, url, headers=h, json=payload, params=params,
                         timeout=30, verify=verify)
    r.raise_for_status()
    data = r.json()
    if not wait or "taskUUID" not in data or not customer_id:
        return data
    task_url = f"{base_url.rstrip('/')}/api/v1/customers/{customer_id}/tasks/{data['taskUUID']}"
    start = time.time()
    while time.time() - start < wait_timeout:
        t = requests.get(task_url, headers=h, timeout=5, verify=verify).json()
        if t.get("percent") == 100 or t.get("status") in ("Aborted", "Failure"):
            return t
        time.sleep(2)
    return t

使用パターン（接続引数を一度スプラットして、その後は忘れる）:

yba = dict(base_url="https://yba.example.com", token=TOKEN, verify=False)
customer_id = yba_request(**yba, endpoint="/api/v1/customers")[0]["uuid"]
yba["customer_id"] = customer_id

universes = yba_request(**yba, endpoint=f"/api/v1/customers/{customer_id}/universes")

スプラットにより、アシスタントは後続の呼び出しをワンライナーとして記述できます — ヘッダーの繰り返しなし、URL ビルドの繰り返しなし、証明書処理の繰り返しなし。

具体的なレシピ（プロバイダー作成、リリースインポート、ユニバース作成、バックアップ、タスクポーリング）は references/recipes.md にあります。自明でないペイロードを生成する前にそのファイルを読んでください — 多くのエンドポイントには明らかでない必須フィールドがあります。

PowerShell

ユーザーが PowerShell で作業している場合は、references/powershell-client.md の単独のラッパー — Invoke-YbaRequest、Get-YbaApiToken、Register-YbaInstance、Get-YbaCustomerId を使用してください。単一の自己完結型 .ps1 ブロック、PowerShell 7 以上のみが必要で、Python ラッパーの形状をミラーリングしています（スプラットされた接続引数、-Wait 経由の taskUUID ポーリング、カスタマー ID キャッシュ）。

ユーザーが既に powershell-yba モジュールをインストールしている場合は、生の Invoke-YbaRequest よりもそのより豊かなリソースごとのコマンドレット（Get-YbaUniverse、New-YbaRelease、New-YbaKubernetesProvider、...）を優先してください — それらは、そうでなければ面倒な v1 ペイロード形状を処理します。両方のサーフェスは -BaseUrl、-ApiToken（SecureString）、-CustomerId、-SkipCertificateCheck を受け入れるため、スプラットは相互運用可能です。

アンチパターン

アンチパターン	結果	代わりに実施してください
別の環境からの customerUUID をハードコードする	403 / Invalid Customer UUID	GET /api/v1/customers 経由で一度検索してキャッシュしてください。
非同期 POST のレスポンスを最終結果として扱う	タスクがまだ実行中で失敗する可能性がある場合、コードはユニバースが直ちに存在すると考える	taskUUID を検出し、percent == 100 または status in (Aborted, Failure) になるまで /customers/{cUUID}/tasks/{taskUUID} をポーリングしてください。
すべてのリクエストで POST /api_login を呼び出す	各ログインはトークンをローテーションし、同時実行スクリプトを破壊する	一度ログインしてトークンを保存し、再利用してください。
v1 ユニバースペイロードを v2 エンドポイントに送信する（またはその逆）	不可解なスキーマエラーで 400	ソースを確認してください: v1 は v1.routes、v2 は openapi/paths/ です。形状は相互運用不可です。
apiToken をエコーまたはログに記録する	トークンリーク — トークンは自動的に期限切れにならない	パスワードのように扱い、WhatIf / ドライラン出力で編集してください。
グローバルで証明書検証をスキップして報告しない	隠れた MITM 露出	明示的な verify=False / -SkipCertificateCheck を要求し、ログに表示してください。
非 2xx JSON レスポンスの error フィールドを無視する	詳細がない一般的な「リクエスト失敗」	YBA はほとんどのエラーで {"error": "..."} を返します — 例外メッセージに表示してください。
v1 でユニバース JSON をゼロから構築する	必須のネストされたフィールドを逃す、編集が沈黙または部分的に失敗する	既存のユニバース（GET /universes/{id}）を読み取り、関連するフィールドを変更し、適切な編集エンドポイントに POST バックしてください。または v2 が利用可能な場合は使用してください。
GET /universes を使用してから名前で文字列マッチングする	メモリにすべてのユニバースをロードする	GET /api/v1/customers/{cUUID}/universes/find?name=<name> を使用して名前を UUID に解決してください。
1 Hz より速くタスクをポーリングする	YBA をハンマー; 一部のエンドポイントはレート制限	1 〜 2 s ポーリング間隔は推奨デフォルトです。

クイックワークフロー: 登録 → トークン → 最初の呼び出し

# 1. 登録（最初の実行時のみ成功）
curl -sk -X POST "$YBA_URL/api/v1/register?generateApiToken=1" \
  -H 'Content-Type: application/json' \
  -d '{"code":"dev","name":"Admin","email":"admin@example.com","password":"<pw>"}'
# →  {"apiToken":"...","customerUUID":"...","userUUID":"..."}

# 2. またはログイン（既存インスタンス — トークンをローテーション）
curl -sk -X POST "$YBA_URL/api/v1/api_login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"<pw>"}'

# 3. トークンを使用する
curl -sk "$YBA_URL/api/v1/customers/$CUSTOMER_ID/universes" \
  -H "X-AUTH-YW-API-TOKEN: $YBA_TOKEN"

これより複雑なもの場合は、Python ラッパーに切り替えてください。