2026年6月14日

DNSimple の API 操作方法｜ゾーンのバックアップ、反映の確認、証明書の DNS 認証に使う

DNS・名前解決

DNSimple の API（v2）は、レコードを1件ずつ書き換えるだけでなく、ゾーン全体の書き出しや、変更がネームサーバーに配られたかの確認にも使えます。この記事では、運用で出番の多い3つの使い方として、全ゾーンの定期バックアップ、変更後の反映確認、Let's Encrypt のワイルドカード証明書を DNS 認証で取る方法を、手順と確かめ方つきで説明します。WordPress サイトのドメインを DNSimple で管理していて、手作業の確認を減らしたい人を想定しています。

API の仕様、トークンの種類、レート制限の値、プラグインの配布方法は変わることがあります（2026年10月現在）。この記事ではエンドポイントの使い方と考え方を中心にし、細かな項目名や上限値は DNSimple の開発者向けドキュメントで確認してください。

準備：トークン・アカウント ID・接続先を変数にする

どの操作でも、アクセストークン、アカウント ID、接続先 URL の3つを使います。スクリプトに直接書かず、環境変数で渡します。

export DNSIMPLE_TOKEN="your-api-token"
export DNSIMPLE_ACCOUNT="your-account-id"
export DNSIMPLE_API="https://api.sandbox.dnsimple.com/v2"   # 本番は https://api.dnsimple.com/v2

アカウント ID が分からない場合は、/v2/whoami を呼ぶと応答にアカウントの情報が入っています。最初はサンドボックス（本番とは別にアカウントとトークンを作る環境）に向けておき、動きを確かめてから本番に切り替えると、誤操作の被害を出さずに試せます。

トークンは用途ごとに分けて発行します。バックアップ用、証明書用と分けておけば、どれかが漏れたときに失効させる範囲が小さくなり、どの仕組みが何をしたかも追いやすくなります。

使い方1：全ゾーンをゾーンファイルとして定期的に書き出す

DNSimple には、ゾーンの内容を BIND 形式のゾーンファイルとして返すエンドポイント（/zones/{ゾーン名}/file）があります。これを全ゾーン分呼んで保存しておくと、誤ってレコードを消したときに元の値を確かめられ、他の DNS へ移るときの材料にもなります。

#!/usr/bin/env bash
# dnsimple-backup.sh: アカウント内の全ゾーンをゾーンファイルとして保存する(読み取りのみ)
set -euo pipefail
: "${DNSIMPLE_TOKEN:?}" "${DNSIMPLE_ACCOUNT:?}"
API="${DNSIMPLE_API:-https://api.dnsimple.com/v2}"
OUT="${1:-./dnsimple-zones}"
mkdir -p "$OUT"
auth=(-H "Authorization: Bearer ${DNSIMPLE_TOKEN}" -H "Accept: application/json")

page=1
while :; do
  res=$(curl -sS --fail "${auth[@]}" "${API}/${DNSIMPLE_ACCOUNT}/zones?per_page=100&page=${page}")
  for zone in $(echo "$res" | jq -r '.data[].name'); do
    curl -sS --fail "${auth[@]}" "${API}/${DNSIMPLE_ACCOUNT}/zones/${zone}/file" \
      | jq -r '.data.zone' > "${OUT}/${zone}.zone"
    echo "saved: ${zone}"
    sleep 1   # 多数のゾーンを続けて取るときの間隔
  done
  total=$(echo "$res" | jq -r '.pagination.total_pages')
  [ "$page" -ge "$total" ] && break
  page=$((page + 1))
done

このスクリプトは読み取りしかしないので、本番のトークンで動かしても DNS の内容は変わりません。押さえておきたい点は次のとおりです。

ゾーン一覧はページ単位で返るため、pagination の総ページ数まで繰り返して取ります。1ページ目だけで終えると、ゾーンが多いアカウントで取りこぼします。
--fail を付けているので、401 や 404 が返ると途中で止まります。止まった場合は、トークンの失効、アカウント ID の違い、サンドボックスと本番の取り違えを順に確かめます。
cron で毎日動かし、保存先を非公開の Git リポジトリにすると、日ごとの差分で「いつ、どのレコードが変わったか」を追えます。ゾーンファイルには所有権確認用の TXT など外に出したくない値も含まれるため、公開リポジトリやウェブから見える場所には置きません。

なお、SOA のシリアル番号は変更のたびに変わるので、差分にはその行も出ます。気になる場合は、差分を見るときに SOA 行を除外すると、実際のレコードの変化だけが目に入ります。

書き出したファイルで確かめておくこと

最初に1回動かしたら、保存されたファイルを開き、管理画面に出ているレコードと見比べます。DNSimple 独自の ALIAS や URL レコードは、標準のゾーンファイルにそのままの形では表現できないため、出力での扱いがほかの種類と異なる場合があります。こうしたレコードを使っているゾーンは、ゾーンファイルだけでなくレコード一覧 API の結果も一緒に保存しておくと、復元や移行のときに迷いません。

使い方2：変更がネームサーバーに配られたかを API で確かめる

レコードの追加や更新の API が成功を返しても、それは DNSimple に登録されたという意味です。DNSimple の各ネームサーバーに行き渡ったかどうかは、ゾーンの配信状態を返すエンドポイント（/zones/{ゾーン名}/distribution）で確かめられます。

curl -sS -H "Authorization: Bearer ${DNSIMPLE_TOKEN}" -H "Accept: application/json" \
  "${DNSIMPLE_API}/${DNSIMPLE_ACCOUNT}/zones/example.com/distribution" | jq '.data.distributed'

true が返れば、ゾーンの内容が DNSimple のネームサーバーに配られています。false のうちは、少し待ってから再度確かめます。個別のレコード単位で確かめるエンドポイントも用意されているので、特定のレコードだけを待ちたいスクリプトではそちらを使います。

API での確認に加えて、実際の応答も dig で見ておくと安心です。

dig +short example.com NS
dig +short www.example.com A @ns1.dnsimple.com

ネームサーバー名は1行目の結果に出たものを使います。権威サーバーで新しい値が返っているのに手元のブラウザで古い表示のままなら、原因は変更前の TTL によるキャッシュです。変更の前日など早めに TTL を短くしておくと、切り替えの待ち時間を短くできます。

使い方3：Let’s Encrypt のワイルドカード証明書を DNS 認証で取る

*.example.com のようなワイルドカード証明書は、HTTP での認証では取れず、_acme-challenge という名前に TXT レコードを置く DNS 認証が必要です。certbot には DNSimple 用のプラグイン（certbot-dns-dnsimple）があり、TXT レコードの追加と削除を API で自動で行えます。

プラグインと認証情報を用意する

certbot を snap で入れている場合はプラグインも snap で、pip で入れている場合は pip で追加します。

# snap の場合
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-dnsimple

# pip(仮想環境)の場合
pip install certbot-dns-dnsimple

トークンは、root だけが読めるファイルに書きます。

# /root/.secrets/certbot/dnsimple.ini
dns_dnsimple_token = your-api-token

sudo chmod 600 /root/.secrets/certbot/dnsimple.ini

権限が緩いままだと certbot が警告を出します。このファイルを持つサーバーが乗っ取られると、トークンの権限の範囲で DNS を書き換えられることになるため、証明書専用のトークンを使い、使わなくなったら失効させます。

証明書を取得し、更新を試す

sudo certbot certonly \
  --dns-dnsimple \
  --dns-dnsimple-credentials /root/.secrets/certbot/dnsimple.ini \
  --dns-dnsimple-propagation-seconds 60 \
  -d example.com -d '*.example.com'

sudo certbot renew --dry-run

--dns-dnsimple-propagation-seconds は、TXT レコードを置いてから Let's Encrypt に確認を頼むまでの待ち時間です。認証が失敗する場合、この値を延ばすと通ることがあります。--dry-run で更新が通れば、以後は certbot の定期実行に任せられます。取得した証明書を Apache や Nginx に設定し、再読み込みする部分は、使っているウェブサーバーの手順に従ってください。

認証が通らないときの確認順

TXT が置かれているか: 認証の途中で dig +short TXT _acme-challenge.example.com @ns1.dnsimple.com を実行し、値が返るかを見ます。返らなければトークンかアカウントの問題で、certbot のログ（通常は /var/log/letsencrypt/letsencrypt.log）に API のエラーが出ています。
ネームサーバーが DNSimple を向いているか: レジストラ側のネームサーバーが別の事業者のままだと、DNSimple に TXT を置いても Let's Encrypt からは見えません。
CAA レコード: ゾーンに CAA レコードがあり、letsencrypt.org が含まれていなければ発行は拒否されます。
待ち時間: 上の3点に問題がなければ、待ち時間を延ばして再度試します。

DNSimple の管理画面にも Let's Encrypt の証明書を発行する機能がありますが、サーバーへの設置や更新の流れは自分で組む必要があります。サーバー上で取得から更新までを完結させたいなら、certbot のプラグインを使うほうが手間が少なく済みます。

まとめ

DNSimple の API は、トークン・アカウント ID・接続先を環境変数で渡し、最初はサンドボックスで試します。
ゾーンファイルのエンドポイントで全ゾーンを定期的に書き出し、非公開の場所に保存しておくと、誤削除や移行のときの控えになります。
変更が配られたかは配信状態のエンドポイントと dig で確かめ、反映の遅れは TTL から判断します。
ワイルドカード証明書は certbot-dns-dnsimple で DNS 認証を自動化でき、トークンは証明書専用にして root だけが読めるファイルで管理します。