オムロン ソーシアルソリューションズのSE村井と申します。

本日は、Nutanix v4 APIの概要、移行時のポイント（注意点含む）を、実際の API 例と共にご紹介していきます。

※この記事はNutanix Advent Calendar 2025年12月19日の記事です。

この記事を見ると何ができるようになる？

• Nutanix v4 API の概要を知ることができる
• Nutanix v4 API への移行時のポイントおよび注意点を知ることができる

どんな人向け？

• Nutanix環境のインフラ管理者
• Nutanix APIを使用しているツールおよびソフトウェア開発者
• REST／JSON／curl／Linux シェル変数／UUID／ETag などの基礎は理解している方

記載ルール

本記事は以下ルールで記載しています。

• 背景色がグレーの文字は、エンドポイント、HTTPメソッド、パラメータ名、キーワード、コード片などです。
• Prism Central VMのIPについては”pc_ip”、Prism ElementのIPは”pe_ip”と記載します。
• Prism CentralのGUIにログインするときのIDを”admin”、パスワードを”P@ssw0rd!”とします。

目次

1. はじめに
2. Nutanix REST API v4 の概要
   • APIバージョンの整理
   • API Namespace一覧
   • 新しいDevelopersポータル（https://developers.nutanix.com/）
3. 具体的に v4 APIでできること
   • 仮想マシン一覧取得とページング
   • 仮想マシンをシャットダウンする（If-Match + NTNX-Request-Id）
   • Nutanix Files のファイルサーバ情報取得
   • 監査情報（Audit）の取得
4. 構成面の注意
5. レガシー API (v0.8 / v1 / v2 / v3) EOS と移行のポイント
   • EOS スケジュール
   • 既存ツール・スクリプトの洗い出し
   • 移行時のポイント
6. 最後に
   • オムロン UPS のv4 APIへの対応予定

1. はじめに

Nutanix は、現在、v0.8 / v1 / v2.0 / v3 / v4のAPIバージョンを提供していますが、2026年 第4四半期に予定されている AOS および Prism Central （以降PC）のアップグレードリリース以降、Nutanix API バージョンのv0.8 / v1 / v2.0 / v3 は廃止され、サポートされなくなります。
そのため、廃止される前に、 v4 APIおよびSDKへの移行を検討していく必要があります。

詳細は、以下API Reference v4 Introductionをご参照ください。
https://www.nutanix.dev/api-reference-v4/

2. Nutanix REST API v4 の概要

APIバージョンの整理

Nutanix は現在、以下の API バージョンを提供しています。

引用元：https://www.nutanix.dev/api-versions/

ポイントは2つです。

・v4 APIは Prism Central が必須
v4 APIは、Prism Central のみが提供する API です。
クライアント（スクリプトやツール）は、Prism Central に対して v4 API を実行（呼び出し） します。
※ クライアント（スクリプトやツール）は、Prism Element に対して v4 API の実行（呼び出し）はできません。
エンドポイントは https://{pc_ip}:9440/api/... になります。

・v3以前のバージョン は 2026年 第4四半期のAOS/Prism Central のアップグレードで EOS
レガシー API に依存している自作スクリプトやツールは、そのタイミングで動かなくなる可能性があります。

API Namespace一覧

v4 APIでは機能ごとにNamespaceで整理されました。

エンドポイントは
/api/vmm/v4.1/ahv/config/vms
/api/monitoring/v4.1/serviceability/audits
のように、/api/Namespace/v4.x/リソースパス というルールで統一されています。

・Prism Centralのバージョンによって、使用できるNamespaceが異なりますので、その点はhttps://www.nutanix.dev/api-reference-v4/ でご確認ください。

新しいDevelopersポータル（https://developers.nutanix.com/）

本ポータルでは、APIとSDK、両方のリファレンスがNamespaceごとに用意されています。

NamespaceごとのAPIを確認すると、Java、JavaScript、Python、Goもサポートされています。
Namespaceごとに、使用するバージョンを選択することができます。

バージョンの命名規則は、vFamily.Revision.[Type]です。

・Family：メジャーバージョンを表しています。(例: v4.2.a1の4の箇所)

・Revision：マイナーバージョンを表します。(例: v4.2.a1の2の箇所)

・[Type]：APIバージョンに関連付けられたオプションのフィールドです。
- 早期アクセスであるEAの場合はa<n> (例: v4.2.a1)です。
- リリース候補のRCの場合はb<n> (例: v4.2.b1)です。
- 製品版APIでは、バージョン文字列にこのTypeフィールドは使用しません。

クエリパラメータとして、OData （Open Data Protocol）による使いやすさ、フィルタリング、並べ替え、抽出項目の選択が強化されました。

v4 API は以下の認証方式をサポートします。

・HTTP Basic 認証（ユーザー名とパスワード）

・IAM（アイデンティティとアクセス管理）API Key 認証

3. 具体的に v4 APIでできること

ここからは、現場でよく使うであろう操作を v4 APIでどう書くかを、curl の例で見ていきましょう。
curl実行環境のOSはrocky linux 9.6を、認証方式はHTTP Basic 認証を使用します。
（URL はサンプルです。バージョン番号などは実際の環境に合わせて調整してください）

仮想マシン一覧取得とページング

v4 APIで 仮想マシンの一覧を取得する代表的なエンドポイントは以下の通りです。

・GET /api/vmm/v4.1/ahv/config/vms

$limit と $page でページングを行います。$limit は 1〜100 の範囲で指定可能 で、省略時はデフォルト 50 件が返されます

# 1 ページ目（$page=0）に最大 100 件の 仮想マシン を取得
curl -k -u 'admin:P@ssw0rd!' ¥
  'https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$limit=100&$page=0'

以下のように変数を割り当てる場合はダブルクォーテーションで囲んでください。（IPはサンプルです。）

export PC_USER=admin
export PC_PASS=P@ssw0rd!
export PC_ADDR=192.168.1.100

curl -k -u "$PC_USER:$PC_PASS" ¥
  "https://$PC_ADDR:9440/api/vmm/v4.1/ahv/config/vms?¥$limit=100&¥$page=0"

※ ダブルクォーテーション内の$limitや$pageが「シェル変数」として解釈されてしまうため、$limitや$pageをエスケープする必要があります。$limitや$pageの$の前に¥を付けて¥$limitや¥$pageと記載します。

OData 形式の $filter を使用して仮想マシン名で絞り込みもできます。

# 仮想マシン名に "WEB" を含む 仮想マシンを50件だけ取得
curl -k -u 'admin:P@ssw0rd!' ¥
'https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$limit=50&$page=0&$filter=contains(name,%27WEB%27)'

※ シングルクォーテーションの中で、シングルクォーテーションを直接書けないため、’WEB’のシングルクォーテーションは%27にURLエンコードします。

変数を使用する、かつ $filter を使用して仮想マシン名で絞り込みをしたい場合

export PC_USER=admin
export PC_PASS=P@ssw0rd!
export PC_ADDR=192.168.1.100

curl -k -u "$PC_USER:$PC_PASS" ¥
"https://$PC_ADDR:9440/api/vmm/v4.1/ahv/config/vms?¥$limit=50&¥$page=0&¥$filter=contains(name,%27WEB%27)"

※ ダブルクォーテーション内の$filterが「シェル変数」として解釈されてしまうため、$filterもエスケープする必要があります。$filterの$の前に¥を付けて¥$filterと記載します。

v3 までとの違いとして、

・仮想マシンの情報を一度に全件取得したい場合も、必ずページング（$limit/$page）を意識する必要があります。

・$filter の構文が OData 準拠で強化されています。

参考情報ですが、100台以上の仮想マシンが存在する場合、metadata.link.hrefとmetadata.link.relの情報を使用すると、現在のページや最終的には何ページまであるのかなどがわかるので、条件分岐などで使えるかもしれません。

$page=0を指定

  "metadata": {
   <省略>
    "links": [
   <省略>
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=2&$limit=100&$orderby=name asc",
        "rel": "last"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=0&$limit=100&$orderby=name asc",
        "rel": "first"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=0&$limit=100&$orderby=name asc",
        "rel": "self"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=1&$limit=100&$orderby=name asc",
        "rel": "next"
      }
    ],
    "totalAvailableResults": 212,

$page=1を指定

  "metadata": {
   <省略>
    "links": [
   <省略>
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=1&$limit=100&$orderby=name asc",
        "rel": "self"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=0&$limit=100&$orderby=name asc",
        "rel": "prev"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=2&$limit=100&$orderby=name asc",
        "rel": "next"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=2&$limit=100&$orderby=name asc",
        "rel": "last"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=0&$limit=100&$orderby=name asc",
        "rel": "first"
      }
    ],
    "totalAvailableResults": 212,

$page=2を指定

  "metadata": {
   <省略>
    "links": [
   <省略>
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=0&$limit=100&$orderby=name asc",
        "rel": "first"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=2&$limit=100&$orderby=name asc",
        "rel": "self"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=1&$limit=100&$orderby=name asc",
        "rel": "prev"
      },
      {
        "href": "https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms?$page=2&$limit=100&$orderby=name asc",
        "rel": "last"
      }
    ],
    "totalAvailableResults": 212,

仮想マシンをシャットダウンする（If-Match + NTNX-Request-Id）

v4 APIでは、既存リソースに対する更新（仮想マシンへの電源操作を含む）は、If-Match と NTNX-Request-Id の 2つのヘッダが必須です。

代表的なエンドポイントは以下の通りです。
・仮想マシンへのACPIシャットダウン

POST api/vmm/v4.1/ahv/config/vms/{extId}/$actions/shutdown

シャットダウン手順の流れ

1) GETで対象 の仮想マシンのヘッダ情報を取得し、 その情報からETag を抽出
2) UUID を生成して NTNX-Request-Id として使用
3)If-Match と NTNX-Request-Id を含めて シャットダウンを実行

1) ヘッダ情報（ETag含む）の取得

# レスポンスヘッダに含まれる ETag を取得
curl -k -u 'admin:P@ssw0rd!' ¥
  -D /tmp/headers.txt ¥
  -o /dev/null ¥
  'https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms/0887ca7c-8be7-48c1-b22f-2e6f94c379e1'

headers.txt の中に例えば次のような行が含まれます（値はサンプルです）。

HTTP/2 200
x-ratelimit-remaining: 39
content-length: 6178
x-content-type-options: nosniff
x-api-ratelimit-limit: 20
content-type: application/json
x-api-ratelimit-reset: 0
etag: YXBwbGljYXRpb24vanNvbg==:NTAsMQ==
set-cookie: NTNX_IAM_SESSION=CgVhZG1pbhDwqfrJBhoHTWVyY3VyeSAAKihhNjI3YjYzOWIxZjQyMjRiZjE1YmViY2UzYWZkZDIzMTczYzhkMzE2|k4Q4IWX0ElH/xDuxE5P9NghATJgRbfIhEvmQUiIRvwI=;Expires=Sun, 14-Dec-2025 10:44:00 GMT;Path=/;Secure;HttpOnly;SameSite=Lax
set-cookie: NTNX_MERCURY_IAM_SESSION=CgVhZG1pbhDwqfrJBhoHTWVyY3VyeSAAKihhNjI3YjYzOWIxZjQyMjRiZjE1YmViY2UzYWZkZDIzMTczYzhkMzE2|k4Q4IWX0ElH/xDuxE5P9NghATJgRbfIhEvmQUiIRvwI=;Expires=Sun, 14-Dec-2025 10:44:00 GMT;Path=/;Secure;HttpOnly;SameSite=Lax
<以降省略>

header.txtからETagのみを抽出し、変数に割り当てます。
必要に応じてechoなどを使用して確認します。

ETAG=$(awk -F': ' 'tolower($1)=="etag"{print $2}' /tmp/headers.txt | tr -d '¥r')
echo "ETAG=${ETAG}"

2) UUIDの生成

REQUEST_ID=$(uuidgen)

NTNX-Request-Id は 各リクエストごとに一意な UUID を付けることで、同じリクエストが二重に送られても処理が重複しないようにするための冪等性トークンです。

※ 同一の仮想マシンに対して、連続でシャットダウン命令を実施する場合も、その都度UUIDの生成が必要です。

3) シャットダウンの実行

curl -k -u 'admin:P@ssw0rd!' ¥
  -X POST ¥
  'https://{pc_ip}:9440/api/vmm/v4.1/ahv/config/vms/0887ca7c-8be7-48c1-b22f-2e6f94c379e1/$actions/shutdown' ¥
  -H "Content-Type: application/json" ¥
  -H "If-Match: ${ETAG}" ¥
  -H "NTNX-Request-Id: ${REQUEST_ID}"

※ Nutanix v4 SDK（Java、JavaScript、Python、Go）を利用した場合は、NTNX-Request-Id の生成や付与は SDK 側で自動的に行われます。curl で実行する（REST APIの）場合のみ設定が必要になります。

Nutanix Files のファイルサーバ情報取得

v4 でNutanix Files の一覧を取得する代表的なエンドポイントは以下の通りです。
・GET /api/files/v4.0/config/file-servers

ファイルサーバの情報を取得します。

curl -k -u 'admin:P@ssw0rd!' ¥
  'https://{pc_ip}:9440/api/files/v4.0/config/file-servers'

「FileServer」というファイルサーバ名と、「5598192f-dfe7-4f69-b450-ecb1a8a7acc8」というextIdを取得できました。

  "data": [
    {
      "$objectType": "files.v4.config.FileServer",
      "$reserved": {
        "$fv": "v4.r1.a1"
      },
      "extId": "5598192f-dfe7-4f69-b450-ecb1a8a7acc8",
      "links": [
        {
          "$objectType": "common.v1.response.ApiLink",
          "$reserved": {
            "$fv": "v1.r0"
          },
          "href": "https://{pc_ip}:9440/api/files/v4.0/config/file-servers/5598192f-dfe7-4f69-b450-ecb1a8a7acc8",
          "rel": "self"
        }
      ],
      "name": "FileServer"
    }
  ],

監査情報（Audit）の取得

運用面でありがたいのが、監査ログ（Audit）を v4 APIで簡単に取得できる点です。Monitoring API は Alerts / Audits / Eventsなどを扱う Namespace になっています。

代表的なエンドポイント例：

・GET /api/monitoring/v4.1/serviceability/audits

・GET /api/monitoring/v4.1/serviceability/audits/{extId}

監査ログでは実施された日時が重要だと思いますが、ログが作成された日時でフィルタをかけることやログが作成された時間でソートができるようになっています。

# 監査イベントを ログが作成された日時順にファイル出力
curl -k -u 'admin:P@ssw0rd!' ¥
  -o /tmp/audit.txt ¥
'https://{pc_ip}:9440/api/monitoring/v4.1/serviceability/audits?$orderby=creationTime'

jqコマンドを利用して必要に応じて整形します。

jq . /tmp/audit.txt > /tmp/audit.json

以下のような監査ログを取得できました。（IPはサンプルです。）

  "data": [
    {
      "$reserved": {
        <省略>
      "extId": "d8e04a4e-86a0-4948-97d9-ac0fe2451a88",
      "sourceEntity": {
        <省略>
        "type": "IAM",
        "name": "admin",
        "extId": "admin"
      },
        <省略>
      "affectedEntities": [
        <省略>
      "operationType": "UPDATE",
        <省略>
      "parameters": [
        {
          "paramValue": {
        <省略>
            "stringValue": "192.168.1.254"
          },
        <省略>
              "paramName": "ip_address"
        },
        {
          "paramValue": {
        <省略>
            "stringValue": "admin"
          },
          "paramName": "audit_user"
        },
        {
          "paramValue": {
        <省略>
            "stringValue": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36"
          },
          "paramName": "browser_info"
        }
      ],
      "operationStartTime": "2025-12-14T13:10:19.174177Z",
      "operationEndTime": "2025-12-14T13:10:19.174177Z",
  <省略>
      "auditType": "IAMAdministrationEventAudit",
      "creationTime": "2025-12-14T13:10:19.176462Z"
    },

Prism CentralのGUIで上記に該当する監査ログを確認すると、以下のような内容が表示されます。

4. 構成面の注意

繰り返しになりますが、v4 APIは、Prism Central のみが提供する API です。

・URL は https://{pc-ip}:9440/api/... です。

・Prism Element のみの環境では v4 API は利用できません。

・v4 APIを使うには、Prism Central の導入と適切なバージョンへのアップグレード が前提になります。

※ v4 APIとAOSおよびPrism Centralの対応バージョンについては、API Reference v4 Introduction（https://www.nutanix.dev/api-reference-v4/）をご参照ください。

そのため、Prism Element に対してv2 API を実行していたツールやソフトウェアを v4 APIに移行する場合は、次のような構成変更が必要になります。

・既存ツールやソフトウェアの接続先を Prism Element → Prism Central に変更します。

・複数のNutanixクラスタが存在する環境など、Nutanixクラスタを指定する必要がある場合は、v4 APIで該当のNutanixクラスタを指定する形に切り替えます。

5. レガシー API (v0.8 / v1 / v2 / v3) EOS と移行のポイント

EOS スケジュール

Nutanix の v4 API Introduction では、以下のように明記されています。

Nutanix Legacy API versions v0.8, v1, v2, and v3 will be deprecated and no longer supported starting with the AOS and PC Upgrade Release planned for Q4-CY2026. Customers with active service contracts will continue to receive support from Nutanix as per the Nutanix EOSL policy. Nutanix strongly recommends that all our customers and partners migrate their applications and tools to the latest v4 APIs and SDKs before the legacy APIs are deprecated.

（日本語訳）
Nutanix のレガシー API バージョンである v0.8、v1、v2、および v3 は、2026 年カレンダーイヤー第4四半期（Q4-CY2026）に予定されている AOS および Prism Central のアップグレードリリース以降、非推奨となり、サポート対象外になります。
有効なサービス契約をお持ちのお客様は、Nutanix EOSL ポリシーに従い、引き続き Nutanix からのサポートを受けることができます。
Nutanix は、すべてのお客様およびパートナーに対し、レガシー API が非推奨となる前に、アプリケーションやツールを最新の v4 API および SDK へ移行することを強く推奨します。

つまり、それ以降のバージョンに AOSおよびPrism Central をアップグレードした瞬間にレガシーAPI（v0.8 / v1 / v2 / v3 ）に依存するツールやソフトウェアは、サポート対象外（場合によっては動作しない）という状況になります。

既存ツール・スクリプトの洗い出し

移行プロジェクトでは、まず次のような観点で棚卸しを行うのがおすすめです。

・どの API バージョンを利用しているか
- https://…/PrismGateway/services/rest/v2.0/
- https://…/api/nutanix/v3/ など

・どの機能を使っているか
- 仮想マシンの一覧取得 / 電源操作 / snapshot / ネットワーク設定 / イメージ管理 / Files など

・外部製品（UPS、バックアップ、監視等）が内部で Nutanix API を使っていないか
その上で、Nutanix の v4 API Migration Guideを見ながら、旧 API → v4 API への対応表を作成していきます。

移行時のポイント

移行時に押さえておきたいポイントを以下に記載します。

1) エンドポイント URL の変更
- /api/nutanix/v3/... → /api/{namespace}/v4.x/...
- Prism Element → Prism Central へ接続先を変更します。

2) データモデルの変更
- API の JSON の構造を前提にした 「JSON の読み取り処理（パースロジック）」 は、v4 APIの data / metadata 形式に合わせて書き直す必要があります。

3) ページングとフィルタリング
- $limit/$page と $filter の組み合わせを前提に実装します。
- 全件抽出する処理は、$page を繰り返しながらマージする必要があります。

4) ETag + If-Match の実装
- 既存エンティティの更新・削除・アクション（power-on/off など）では、
✓ 事前 GET → ETag 取得
✓ If-Match: {ETag} を付与
✓ ETag 不一致時は 412/428 などのエラーをハンドリング

5) NTNX-Request-Id による冪等性
- 同一リクエストがネットワークリトライ等で複数回送信されても、同じ Request-Id であれば再実行されないように設計されています。
- ツールやソフトウェアで REST APIを実行するときは UUID の生成とヘッダ付与を忘れないようにします。

6) テスト環境での検証
- 可能であれば、v4 API対応版のツールやソフトウェアを 別の テスト環境で十分に検証してから本番に適用します。

6. 最後に

オムロン UPS のv4 APIへの対応予定

現在のオムロン UPS のシャットダウンソフト（Nutanix 連携機能）は、Prism Element の REST API v1 / v2 を利用して仮想マシンや状態取得やシャットダウンを行っています。

例：
- 停電検知 → Nutanix v2 API を実行し、仮想マシンを順番にシャットダウンします。
- v1/v2 のエンドポイントは
https://{pe_ip}:9440/PrismGateway/services/rest/v2.0/... のような形です。

オムロン UPS のシャットダウンソフトについては、今後 Nutanix REST API v4 にも対応していく予定です。
v4 API対応時には、少なくとも次のような変更が入るイメージになります。

・接続先を Prism Element → Prism Central に変更します。

・仮想マシンの状態取得を v4 APIの vmm Namespace 経由で行います。
- 例： GET /api/vmm/v4.1/ahv/config/vms?$limit=100

・仮想マシンのシャットダウン（shutdown / guest-shutdown）では、事前に仮想マシンの ETag を取得しIf-Match と NTNX-Request-Id を付与して $actions/shutdown を実行します。
- 複数回実行しているACPIシャットダウンについては、都度UUIDを生成します。

・v4 API が Prism Central 経由のため、Prism Central VMを最後にシャットダウンします。

この記事をベースに、まずはテスト環境で v4 APIを触ってみて、「自分たちの運用にとって、どの Namespace をどう使うか」を整理していくきっかけにしていただければ幸いです。

それでは、また次回お会いしましょう！