さくらのDNS でAPI操作する手順｜さくらのクラウド API でレコードを取得・追加・変更・削除する

さくらのクラウドの DNS（DNS アプライアンス）は、さくらのクラウド API で操作できます。いちばん大事な点は、レコードの更新が「ゾーンのレコード一覧をまるごと送って置き換える」方式であることです。1件だけ追加したいときも、今の一覧を取得して1件足し、全件を送り返す手順を守らないと、ほかのレコードが消えてしまいます。この記事では、API キーの準備、ゾーンの ID の調べ方、取得・追加・変更・削除の安全な手順、反映の確かめ方を、curl と jq を使って説明します。

API のエンドポイントや応答の項目、コントロールパネルの表記は変わることがあります（2026年10月現在）。実際の作業では、さくらのクラウドの公式 API ドキュメントと照らし合わせてください。

対象になる「さくらのDNS」を確かめる

さくらインターネットには DNS に関わるサービスがいくつかあります。この記事が扱うのは、さくらのクラウドのコントロールパネルでゾーンを作る DNS アプライアンスです。ゾーンを作ると ns1.gslb○.sakura.ne.jp のようなネームサーバーが割り当てられ、レジストラでそのネームサーバーを登録して使います。

さくらのドメインやさくらのレンタルサーバの会員メニューで行うゾーン編集は、別のサービスです。こちらを一般向けの API で操作する方法は案内されていないため、スクリプトから操作したい場合は、DNS アプライアンスにゾーンを移すことになります。今使っているのがどちらかは、dig example.com NS +short で返るネームサーバー名で見分けられます。

手順1：API キーを用意する

コントロールパネルで API キーを作成すると、アクセストークンとアクセストークンシークレットの組が発行されます。API キーにはアクセスできる範囲（閲覧だけか、設定の編集もできるか など）を選ぶ項目があるので、DNS のレコードを書き換える用途なら、その作業に必要な範囲だけを許可します。用途ごとにキーを分けておくと、漏れたときに止める範囲を小さくできます。

認証は HTTP の Basic 認証で、ユーザー名にトークン、パスワードにシークレットを使います。コマンドラインの引数に書くとシェルの履歴やプロセスの一覧に残るので、権限を絞ったファイルから読ませます。

# ~/.sakura-netrc（chmod 600 にする。値は発行されたものに置き換える）
machine secure.sakura.ad.jp
login your-access-token
password your-access-token-secret

chmod 600 ~/.sakura-netrc
API=https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1

例ではエンドポイントのゾーン部分を is1a にしています。DNS のようなゾーンに依存しないリソースを扱うときのエンドポイントは、公式の API ドキュメントで確認してください。シークレットは Git のリポジトリやチャットに貼らないようにします。

手順2：ゾーンの ID を調べる

DNS のゾーンは、API の上では「共通サービスアイテム（commonserviceitem）」の一種として扱われます。一覧を取得して、DNS のものだけを選び出します。

curl -s --netrc-file ~/.sakura-netrc "$API/commonserviceitem" \
  | jq '.CommonServiceItems[] | select(.Provider.Class == "dns") | {ID, Name, NS: .Status.NS}'

Name がゾーン名（example.com）、ID が以後の操作で使う番号、NS が割り当てられたネームサーバーです。応答が 401 なら、トークンとシークレットの組み合わせか、ファイルのホスト名の書き方を見直します。

手順3：レコード一覧を取得してバックアップする

更新の前に、今のレコード一覧を日時付きのファイルに保存します。置き換えに失敗したときは、このファイルの中身を送り直せば元に戻せます。

ID=123456789012   # 手順2で調べた ID
TS=$(date +%Y%m%d%H%M%S)

curl -s --netrc-file ~/.sakura-netrc "$API/commonserviceitem/$ID" > "zone-$TS.json"
jq '.CommonServiceItem.Settings.DNS.ResourceRecordSets' "zone-$TS.json" > current.json
jq 'length' current.json

各レコードは、Name（ゾーン内の名前。頂点は @）、Type、RData（値）、TTL の組で表されます。MX の優先度や TXT の引用符、末尾のドットの付け方は、すでに登録されている同じ種類のレコードを見て、同じ書き方にそろえるのが安全です。

手順4：レコードを追加・変更・削除する

どの操作も、current.json を jq で書き換えて new.json を作り、差分を見てから全件を送る、という流れは同じです。

# 追加: blog.example.com の A レコード
jq '. + [{"Name":"blog","Type":"A","RData":"203.0.113.20","TTL":600}]' current.json > new.json

# 変更: www の A レコードの値を差し替える
jq 'map(if .Name == "www" and .Type == "A" then .RData = "203.0.113.30" else . end)' current.json > new.json

# 削除: old の CNAME を外す
jq 'map(select((.Name == "old" and .Type == "CNAME") | not))' current.json > new.json

送る前に、差分と件数を確かめます。

diff <(jq -S . current.json) <(jq -S . new.json)
echo "before: $(jq length current.json)  after: $(jq length new.json)"

差分が意図した1件だけになっていれば、全件を送ります。件数が0件や極端に少ない場合は送らないように、スクリプトで止めておくと事故を防げます。

n=$(jq length new.json)
[ "$n" -gt 0 ] || { echo "new.json が空なので中止"; exit 1; }

jq '{CommonServiceItem: {Settings: {DNS: {ResourceRecordSets: .}}}}' new.json > body.json
curl -s --netrc-file ~/.sakura-netrc -X PUT \
  -H 'Content-Type: application/json' --data @body.json \
  "$API/commonserviceitem/$ID" \
  | jq '.CommonServiceItem.Settings.DNS.ResourceRecordSets | length'

応答に含まれるレコード数が new.json と同じであれば、置き換えは受け付けられています。

手順5：反映を確かめる

API の応答が成功でも、ネームサーバーが新しい値を返しているかは別に確かめます。キャッシュの影響を避けるため、手順2で表示されたネームサーバーへ直接問い合わせます。

dig @ns1.gslb1.sakura.ne.jp blog.example.com A +norec +short
dig @ns2.gslb1.sakura.ne.jp blog.example.com A +norec +short

ネームサーバー名は実際に割り当てられたものに置き換えます。ネームサーバーが新しい値を返していれば作業は完了で、ブラウザなどで古い値が見えるのは、変更前の TTL の間キャッシュが残っているためです。値を頻繁に切り替えるレコードは、事前に TTL を短くしておくと待ち時間を減らせます。

つまずきやすい点

• 同時に更新すると片方の変更が消える：全件置き換えなので、2つのスクリプトや人の手作業が同時に「取得→送信」を行うと、後から送ったほうの内容で上書きされます。更新を1か所に集め、実行を順番に並べます。取得時の応答には設定の状態を表す値が含まれ、更新時の競合検出に使える場合があるので、公式ドキュメントで扱いを確認してください。
• JSON の書き方の誤り：TXT の値に含まれる引用符や DKIM の長い値は、手で JSON を組み立てると壊れやすい部分です。jq の --arg で文字列を渡すと、エスケープを jq に任せられます。
• 相対名と完全修飾名の混同：Name にゾーン名まで含めて書くと、意図しない名前になることがあります。既存のレコードの書き方に合わせます。
• レコード数や TTL の制限：登録できる件数や TTL の範囲には上限・下限があります。値はサービスの仕様ページで確認します。

手作業のスクリプトから先へ進めるとき

レコードの変更が日常的にある場合は、手書きの curl を増やすより、既存の道具を使うほうが安全です。

• usacloud：さくらのクラウド用のコマンドラインツールで、DNS のゾーンとレコードも扱えます。サブコマンドの書き方はバージョンで変わっているため、usacloud dns --help で確かめます。
• Terraform：さくらのクラウド用のプロバイダーで、ゾーンとレコードをコードとして管理できます。全件置き換えの扱いをツールに任せられ、terraform plan で差分を見てから反映できます。
• 証明書の DNS-01 認証：Let's Encrypt のワイルドカード証明書などで TXT レコードを自動で出し入れしたい場合は、lego などさくらのクラウドに対応した ACME クライアントを使う方法があります。対応状況はツールのドキュメントで確認してください。

どの道具でも、認証情報は環境変数や権限を絞ったファイルから渡し、最初はテスト用のゾーンで動きを確かめてから本番のゾーンに使います。

まとめ

• 対象はさくらのクラウドの DNS アプライアンスです。会員メニューのゾーン編集とは別のサービスなので、まず NS で見分けます。
• API キーは必要な範囲だけを許可し、シークレットは権限を絞ったファイルから読ませます。
• レコードの更新は全件置き換えです。取得してバックアップし、jq で書き換えて差分と件数を見てから送ります。
• 反映は割り当てられたネームサーバーへ dig で直接問い合わせて確かめます。
• 同時更新に注意し、日常的に変更するなら usacloud や Terraform に移します。

• digコマンドでDNSレコードを調査する方法｜出力の読み方と調査の定番パターン
• DNSのTTLの意味と適切な設定方法｜用途別の目安と変更前の下準備