API

API で Safe Update を実行する方法

自社の保守管理画面などから NexraOne の API を呼び出して、サイトごとの更新対象を取得し、プラグインを指定して Safe Update を実行し、結果を受け取る方法です。API キーの発行、呼び出し回数の上限、Webhook の受け取り方も説明します。

このページで分かること

設定前に確認すること、操作手順、運用時に注意したいポイントを順番に確認できます。

READY事前確認

Business 以上のプラン、または OEM のご契約であること

キーを発行するのは、チームのオーナーの権限で行うこと

Safe Update を実行するサイトに NexraOne Agent が接続されていて、管理画面からの Safe Update が使えること

STEPS手順
1

設定の「API」でキーを発行する

チームのオーナーが、設定の「機能ごとの設定」にある「API」を開き、「キーを発行」を押します。名前には「保守管理画面(本番)」のように、どこで使うキーか分かるものを付けてください。できることは「読み取りのみ」と「読み取りと Safe Update の実行」から選びます。更新対象を一覧に出すだけなら読み取りのみで足ります。発行したキーの全文は、そのダイアログを閉じると二度と表示されないので、その場で保存先に控えます。NexraOne にはキーそのものを残していないため、なくした場合は無効にして発行し直してください。

2

サイトの一覧と更新対象を取得する

キーは Authorization ヘッダーに Bearer を付けて送ります。サイトの一覧で siteId を確かめ、サイトごとの更新対象を取得すると、WordPress 本体・テーマ・プラグインの今の版と新しい版が返ります。compatible が false の項目は、サイトの PHP や WordPress の版が足りず、Safe Update を実行しても対象から外れるものです。unsupported には、WordPress.org に登録がない有料プラグインや NexraOne Agent 自身など、NexraOne から更新できないものが入ります。Agent は WordPress の管理画面から更新してください。

curl https://api.nexraone.app/api/v1/sites \
  -H "Authorization: Bearer nxo_live_..."

curl https://api.nexraone.app/api/v1/sites/{siteId}/updates \
  -H "Authorization: Bearer nxo_live_..."
3

プラグインを指定して Safe Update を実行する

更新する項目を updates に並べて送ります。toVersion には、更新対象の取得で受け取った newVersion をそのまま入れてください。承認したあとにさらに新しい版が出ていた場合は、承認していない版へ上げないよう 422 version_mismatch で断ります。Idempotency-Key ヘッダーは必須で、同じ値で送り直すと 24 時間以内なら最初の応答をそのまま返します。通信が切れて結果が分からなかったときも、同じキーで送り直せば二重に実行されません。受け付けると 202 と実行の ID が返り、実際の更新は管理画面から実行したときと同じ流れで進みます。

curl -X POST https://api.nexraone.app/api/v1/sites/{siteId}/safe-updates \
  -H "Authorization: Bearer nxo_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2026-10-28-site123-001" \
  -d '{"updates":[{"type":"plugin","slug":"contact-form-7","toVersion":"6.1.1"}]}'
4

実行の状態と結果を確かめる

実行の ID で状態を取得します。status は scheduled(予約中)、queued(順番待ち)、running(実行中)、succeeded(完了)、failed(失敗)、rolled_back(ロールバック)、needs_review(要確認)、cancelled(取り消し)のどれかです。実行中は phase に今の段階が backing_up(バックアップ)、updating(更新)、verifying(更新後の確認)、rolling_back(更新前へ戻している)のどれかで入ります。items には、まだ手を付けていない項目も含めて、項目ごとの更新前と更新後の版と、pending(未着手)・running(更新中)・updated・failed・rolled_back・skipped の状態が入ります。1つのプラグインの中で何%進んだかは分かりません。失敗やロールバックの理由は result に、画面で確かめるためのリンクは dashboardUrl に入ります。何度も取得し直すより、次の Webhook で知らせを受けるほうが呼び出し回数を使いません。

curl https://api.nexraone.app/api/v1/safe-updates/{id} \
  -H "Authorization: Bearer nxo_live_..."
5

Webhook で結果を受け取る

設定の「API」で、https で始まる受け取り用の URL を登録します。登録したときに一度だけ表示される署名用のシークレットを控え、届いたリクエストが NexraOne から来たものかを確かめてください。X-Nexraone-Webhook-Timestamp の値と本文を「.」でつないだ文字列を、シークレットで HMAC-SHA256 にかけた値が、X-Nexraone-Webhook-Signature の v1= のあとの値と一致すれば本物です。タイムスタンプが5分以上ずれているものは捨ててください。2xx を返さなかったときは、1分、5分、30分、2時間、6時間の間隔で最大6回送ります。同じ知らせが二度届くことがあるので、X-Nexraone-Webhook-Id で重複を除いてください。

import crypto from "node:crypto";

function isValid(rawBody, headers, secret) {
  const ts = headers["x-nexraone-webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const given = headers["x-nexraone-webhook-signature"] ?? "";
  return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
REFERENCEエンドポイントとイベント

すべて https://api.nexraone.app/api/v1 から始まります。成功したときは data に、失敗したときは error の code と message に中身が入ります。code は英語の決まった値なので、画面の出し分けには message ではなく code を使ってください。

GET/sitesサイトの一覧。environment(production など)で絞り込み、cursor で続きを取得
GET/sites/{siteId}/updatesWordPress 本体・テーマ・プラグインの更新対象
POST/sites/{siteId}/version-checkWordPress.org に新しい版を問い合わせ直す。同じサイトは10分に1回まで
POST/sites/{siteId}/safe-updatesSafe Update の実行(Safe Update の実行権限があるキーだけ)
GET/safe-updates/{id}実行の状態と結果
GET/sites/{siteId}/safe-updatesサイトの実行履歴。status と since で絞り込み、新しい順
POST/safe-updates/{id}/cancel予約中(scheduled)の実行の取り消し

Webhook のイベント

本文の data には、状態の取得と同じ形の safeUpdate、サイトの名前と URL、どこから実行したか(api・dashboard・auto)が入ります。管理画面から実行したものや自動 Safe Update の結果も届くので、API から実行したものだけを扱う場合は trigger で絞り込んでください。

safe_update.started更新を始めた
safe_update.completedすべての項目を更新し、確認も通った
safe_update.failedサイトに変更を加える前に止まった、または更新に失敗した
safe_update.rolled_back更新後の確認で問題が見つかり、更新前に戻した
safe_update.needs_review自動では戻しきれず、画面で確かめてほしい状態になった
safe_update.cancelled予約や順番待ちのまま取り消された

呼び出し回数の上限

キーごとに、読み取り(GET)は1分に60回、実行や取り消しなどの書き込みは1分に10回までです。応答の X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset で残りの回数が分かります。上限を超えると 429 rate_limited が返るので、Retry-After の秒数だけ待ってから送り直してください。

NOTES補足

API から実行した Safe Update も、管理画面から実行したときと同じ条件で断られます。サイトが落ちている、別の Safe Update が動いている、Agent の版が古いといった場合は 409 と理由の code が返ります。

API から実行したものは、管理画面の履歴に「API(キーの名前)」と出ます。監査ログにも、どのキーで実行したかが残ります。

自動 Safe Update の連続失敗の数には、API から実行したものの失敗を含めません。

キーが漏れたかもしれないときは、設定の「API」で無効にしてください。次の呼び出しから断ります。すでに始まっている Safe Update は止まりません。