IPv6 ダイナミック DNS API マニュアル

「IPv6 ダイナミック DNS」サービスのほぼすべての操作 (DDNS ホストの新規作成、IPv6 アドレスの更新、削除など) は、本 Web サイトから行うことができます。

しかしながら、数十個、数百個の IoT 機器や VPN ルータなどを広範囲に設置しようとする場合に、本 Web サイトのフォーム上で何度もホストの作成操作を行おうとすると、手数や時間がかかります。

そこで、本サービスでは、本 Web サイト上から行うことができるすべての操作について、より簡易的な HTTP API を準備し、HTTP API によるタスクの自動化を可能にしています。

HTTP API の考え方

シンプルなデータフォーマット

HTTP API は、任意の HTTP GET メソッド対応の HTTP クライアント・プログラムから呼び出すことができます。以下のように、呼び出しパラメータはすべてシンプルな QueryString 指定系の API となっており、また、応答されるデータはすべて CSV 形式となっています。したがって、HTTP API は、マイコンや IoT 機器などの省リソースの CPU やプログラムから呼び出すことができます。REST や SOAP のような複雑なクエリ文字列の生成、レスポンス文字列のパース処理は不要です。

HTTPS による高いセキュリティ

以下のすべての HTTP API は、「http://」という部分を「https://」に変更することにより、HTTPS 通信として呼び出すことが可能です。これにより、インターネットを経由して HTTP API を呼び出す際のセキュリティを高めることができます。

ただし、本 HTTP API は、マイコンや IoT 機器などの省リソースの CPU やプログラムから呼び出すことも想定しており、これらの小型機器では証明書チェーンの検証や SSL (TLS) の暗号化処理が難しい場合も多いことから、本サービスでは、今後も HTTP API を継続的に提供していく方針です。

IPv6 プロトコルによる API の呼び出しが可能 (フレッツ網内からのみ呼び出し可能)

本 HTTP API は、すべて IPv6 プロトコルから呼び出すことができます。

• IPv6 版 API は、NTT 東日本の 「フレッツ光」の IPv6 ネットワーク内から呼び出すことができます。
• 本 API サーバーは、NTT 東日本のフレッツ・光ネクスト網内に接続されていますので、NTT 東日本の 「フレッツ光」の IPv6 ネットワーク内 (網内折り返し通信) から本サービスの HTTP API の IPv6 版を呼び出す場合は、インターネット接続契約は必要ありません。
• なお、HTTPS API として呼び出すことができます。

レスポンス文字列

本 HTTP API にリクエストを送付すると、レスポンス文字列として以下のような UTF-8 テキストフォーマットが返却されます。

正常に処理された場合 (例)

緑色の文字列は、コメントです。実際に入力する必要はありません。

RESULT:OK ← エラーコード。"OK" の場合は正常、それ以外はエラー。
RESULT_JA:正常に処理されました。 ← エラーコードの日本語解説文字列。ユーザーにはこの文字列をそのまま表示すれば良い。
RESULT_EN:The request has sucessfully completed. ← エラーコードの英語解説文字列。日本語を表示できない環境で表示する場合に便利。
RESULT_SIZE:123 ← このレスポンス部分に続く付加データのバイト数。
以下、CSV データ等

エラーが発生した場合 (例)

緑色の文字列は、コメントです。実際に入力する必要はありません。

RESULT:SearchByMailAddressNotFound ← エラーコード。"OK" の場合は正常、それ以外はエラー。
RESULT_JA:指定されたメールアドレスで登録されているホスト情報が見つかりません。← エラーコードの日本語解説文字列。ユーザーにはこの文字列をそのまま表示すれば良い。
RESULT_EN:No registered DDNS hosts found with the specified email address. ← エラーコードの英語解説文字列。日本語を表示できない環境で表示する場合に便利。
RESULT_SIZE:15 ← このレスポンス部分に続く付加データのバイト数。
aaa@example.com

上記のように、「RESULT:」の行から「RESULT_SIZE:」の行までの間は、共通のエラーデータが記述されます。

「RESULT_SIZE:」の行は、共通のエラーデータ記述の最後に挿入されます。その後に、エラーデータを補足する拡張文字列が付加されます。

共通記述行は、現在のところ上記のみですが、今後増加する場合があります。ただし、その場合も、必ず最後は「RESULT_SIZE:」の行で終了しますので、エラー処理をプログラムで行う場合は、「RESULT_SIZE:」の行までで既知のフィールドを読み取るような処理にしてください。

HTTP API エラーコードの一覧

DDNS ホスト IPv6 アドレス 更新 API (Renew API)

この API は、DDNS ホストに関連付けられている IPv6 アドレス (すなわち、そのホスト名に対する DNS クエリに対して本サービスから応答される AAAA レコード内の IPv6 アドレス) を更新 (変更) します。

HTTP リクエスト例

IPv6 版: http://ddnsapi-v6.e-ntt.jp/api/renew/?7AF958665BEB601253=2001:db8::1&41C705C4834C608A82=2002::2

• パラメータとして、上記のように、DDNS ホストキーを指定します。
• DDNS ホストキーに続いてイコール文字 (=) を書き、次に上記のように IPv6 アドレスを指定します。
  (IPv6 アドレスを省略することもできます。その場合の挙動は、下述のとおりです。)
• 一回の API 呼び出しで、複数の (最大 1024 個) DDNS ホストの IPv6 アドレスを更新することができます。上記の例では、2 つのホスト (7AF958665BEB601253, 41C705C4834C608A82) を同時に更新しています。もちろん、1 個のみ更新することもできます。
• 新しい IPv6 アドレスを明示的に指定しない場合 (DDNS ホストキーのみ指定した場合) の挙動は、以下のとおりです。
  • IPv6 版の API が呼び出された場合は、その API の呼び出し元の HTTP クライアントの IPv6 アドレスが設定されます。すなわち、たとえばコンピュータからこの API を呼び出すと、そのコンピュータの LAN カード (eth0 など) の IPv6 アドレスが設定されることになります。これは、たとえば VPN ルータや IoT 機器などから定期的に本 HTTP URL を呼び出す設定にすることで、当該機器等の IPv6 アドレスを常に DDNS ホスト名に対して更新し続ける挙動を実現するために便利です。

HTTP レスポンス例

RESULT:OK
RESULT_JA:正常に処理されました。
RESULT_EN:The request has sucessfully completed.
RESULT_SIZE:683
#Key,Fqdn,Hostname,IPv6,UpdateHostFqdn,UpdateHostIPv6,Mail,Create,LastRenew,LastQuery,NumRenew,NumQuery,CreateSrcIP,LastRenewSrcIP
※ 「1. DDNS ホスト新規登録 API (New API)」と同等のフィールド一覧 (API 呼び出し時点の最新情報) が、CSV で返却されます。

DDNS ホスト IPv6 アドレス 更新 API (Renew API)

この API は、DDNS ホストの最新状態を取得します。

「1. DDNS ホスト新規登録 API (New API)」の「備考」に列挙されているフィールド一覧と同一の情報を取得することができます。多数の DDNS ホストを管理している際に便利です。

HTTP リクエスト例

IPv6 版: http://ddnsapi-v6.e-ntt.jp/api/status/?7AF958665BEB601253

• パラメータとして、上記のように、DDNS ホストキーを指定します。
• なお、DDNS ホストキーの代わりに、DDNS ホスト名を指定することもできます。この場合は、一部の秘密情報 (ホストキーなど) は *hidden* と表示され、取得できません。
• 一回の API 呼び出しで、複数の (最大 1024 個) DDNS ホストの情報を取得することができます。上記の例では、1 つのホスト (7AF958665BEB601253) の情報を取得しています。もちろん、2 個以上のホスト情報を同時に取得することもできます。

HTTP レスポンス例

RESULT:OK
RESULT_JA:正常に処理されました。
RESULT_EN:The request has sucessfully completed.
RESULT_SIZE:683
#Key,Fqdn,Hostname,IPv6,UpdateHostFqdn,UpdateHostIPv6,Mail,Create,LastRenew,LastQuery,NumRenew,NumQuery,CreateSrcIP,LastRenewSrcIP
※ 「1. DDNS ホスト新規登録 API (New API)」と同等のフィールド一覧 (API 呼び出し時点の最新情報) が、CSV で返却されます。

DDNS ホスト変更履歴取得 API (History API)

この API は、DDNS ホストに関する最近の変更履歴を表示します。変更履歴は、直近の 10 件程度が表示されます。

当該 DDNS ホストに関連付けられている IPv6 アドレスがいつ、どのような理由で変更されたのかをまとめて取得することができます。

HTTP リクエスト例

IPv6 版: http://ddnsapi-v6.e-ntt.jp/api/history/?7AF958665BEB601253

• パラメータとして、上記のように、DDNS ホストキーを指定します。
• 一回の API 呼び出しで、複数の (最大 1024 個) DDNS ホストの情報を取得することができます。上記の例では、1 つのホスト (7AF958665BEB601253) の情報を取得しています。もちろん、2 個以上のホスト情報を同時に取得することもできます。

HTTP レスポンス例

RESULT:OK
RESULT_JA:正常に処理されました。
RESULT_EN:The request has sucessfully completed.
RESULT_SIZE:736
#SeqNo,TimeStamp,Key,Fqdn,Hostname,Action,Ip,ApiType,LastQuery,ApiSrcIp
10235,20160611_150419,7AF958665BEB601253,neko1.i.e-ntt.jp,neko1,new,2001:db8::1,httpapi,2401:af80:8000:0:38c0:dc35:b5a3:d55e
10245,20160611_150748,7AF958665BEB601253,neko1.i.e-ntt.jp,neko1,renew,::1,httpapi,2001:db8:8000:0:38c0:dc35:b5a3:d55e
10248,20160611_150836,7AF958665BEB601253,neko2.i.e-ntt.jp,neko2,changehostname,::1,httpapi,2001:db8:8000:0:38c0:dc35:b5a3:d55e
10250,20160611_151133,7AF958665BEB601253,neko2.i.e-ntt.jp,neko2,renew,2001:db8:8000:0:38c0:dc35:b5a3:d55e,update-packet,2401:af80::123
10251,20160611_151208,7AF958665BEB601253,neko2.i.e-ntt.jp,neko2,renew,12::43,web,2001:db8:8000:0:38c0:dc35:b5a3:d55e

備考: CSV で返却されるデータのカラムの内容

• SeqNo: シーケンス番号 (本システム全体でユニークな連番)
• TimeStamp: イベント発生日時
• Key: DDNS ホストキー (18 文字)
• Fqdn: DDNS ホストの FQDN (フル形式のホスト名 + ドメイン名)
• Hostname: DDNS ホスト名
• Action: イベント内容 (new: 新規作成, renew: IPv6 アドレス更新, changehostname: ホスト名の変更, delete: 削除)
• Ip: イベント発生原因の要求元 IP アドレス
• ApiType: イベント発生原因となった API 要求の種類 (http, web, update-packet 等)
• LastQuery: DDNS ホストに対する名前解決クエリがあった最終日時
• ApiSrcIp: API 呼び出し元 IP アドレス

CSV で返却されるカラムは、今後追加される可能性があります。また、カラムの順序は変更となる可能性があります。そのため、CSV 応答を受信するプログラムは、CSV の 1 行目に記載されているカラム一覧をパースし、何番目のカラムがどの情報を含んでいるか判別をする必要があります。

ping 等を送信することによる DDNS ホストの IPv6 アドレス更新等の挙動に関する仕様書

DDNS ホストを作成した後に提供される「更新専用ホスト名」または「更新専用アドレス」によって示される IPv6 アドレスに対して、何らかの IPv6 パケット (UDP または ICMP であればいずれでも可) を 1 パケット以上送信すると、その瞬間に、当該 DDNS ホストに関連付けられている IPv6 アドレスが、当該 IPv6 パケットの送信元 IPv6 アドレス (IPv6 パケットのソースアドレス) に書き換わります。

これは、スクリプトを定期的に動作させることができない専用デバイスや IoT 機器での使用方法で説明されているように、HTTP API を定期的に呼び出すクライアントスクリプトや cron デーモンなどを動作させることができない (ユーザーに対してそのようなカスタマイズを行う手段を提供していない) IoT デバイスや各種 IPv6 対応電子機器 (監視カメラ等) を本 DDNS サービスと共に利用したい場合に大変便利です。

「更新専用ホスト名」または「更新専用アドレス」で示される IPv6 アドレスに、本サービスの特殊な API サーバーが動作しています。当該 API サーバーは、「更新専用ホスト名」または「更新専用アドレス」で示される IPv6 アドレス宛の着信パケットを常に Listen しています。任意の IPv6 パケットが届いたことを検出すると、その IPv6 パケットの種類が何であっても、対応する DDNS ホストに係る IPv6 アドレスを、当該 IPv6 パケットのソースアドレスに書き換えます。

したがって、「更新専用ホスト名」または「更新専用アドレス」で示される IPv6 アドレスは一種の秘密鍵 (パスワード) としての性質を有します。実際、18 文字のホストキー文字列には 72 bit のデータが含まれ、72 bit の秘密鍵として作用していますが、「更新専用ホスト名」または「更新専用アドレス」で示される IPv6 アドレスの末尾 72 bit の IPv6 アドレスデータはこの 72 bit のホストキーと同一のビット列によって構成されています。「更新専用ホスト名」または「更新専用アドレス」で示される IPv6 アドレスを他人に教えることは、ホストキーを他人に教えることと同一の意味を有しますから、必要がない限り、「更新専用ホスト名」または「更新専用アドレス」で示される IPv6 アドレスを他人に教えないようにしてください。

「更新専用ホスト名」または「更新専用アドレス」で示される IPv6 アドレスに、IPv6 パケットを送付した場合は、以下のような応答パケットを返す場合があります。

• ICMP Echo パケットを送信した場合は、ICMP Reply パケットが返却されます (ただし、パケットロス等の技術上の理由によりパケットが消失することがあり、必ず返却される保証はありません)。
• DNS クエリパケットを送信した場合は、DNS レスポンスパケットが返却されます。この場合は、IPv4 および IPv6 インターネットから取得したレスポンス結果が格納されることが期待できます (ただし、保証はされません)。
• NTP クライアントパケットを送信した場合は、現在時刻が返却されます (ただし、パケットロス等の技術上の理由によりパケットが消失することがあり、必ず返却される保証はありません)。
• その他のパケットを送付した場合は、無視されるか、ICMP エラーが返却されます。

その他、以下のような注意点があります。

• 「更新専用ホスト名」 (FQDN) は本サービスが継続する限り永続的ですが、「更新専用アドレス」の IPv6 アドレスは変更になる可能性があります。
• したがって、やむを得ない事由がない限り、デバイス側には 「更新専用ホスト名」 (FQDN) を指定するようにしてください。

本機能の使用方法について、詳しくは、以下のリンクをクリックしてください。

スクリプトを定期的に動作させることができない専用デバイスや IoT 機器での使用方法