レコード¶

レコードオブジェクト¶

リソースレコードを作成する時や編集する時は、 POST リクエストや PUT リクエストのボディとして JSON 形式のレコードオブジェクトを送信します。

共通プロパティ¶

次のプロパティはリソースタイプに関わらず共通して指定します。

.type で指定するリソースタイプに応じて .records[] 配列の要素に指定するオブジェクトの形式が異なります。詳しくはそれぞれのセクションをご覧ください。

プロパティ	型	説明
.id	string	レコードを一意に特定する ID (read-only)
.name	string	ドメイン名（オーナーネーム）
.type	string	以下のいずれかのリソースタイプ A NS CNAME MX TXT AAAA SRV SVCB HTTPS CAA
.enable_alias	boolean	エイリアス利用有無以下のリソースタイプでご利用になれます。 A AAAA MX （非推奨） TXT （非推奨） SRV （非推奨）
.alias_to	string	エイリアス先
.ttl	integer	TTL
.records[]	array	`.type` で指定したリソースタイプに応じたレコードオブジェクトのリスト

ドメイン名の指定方法¶

レコードオブジェクト内におけるドメイン名の指定方法は次の 3 通りがあります。

絶対名 (FQDN)

末尾がドットで終わるドメイン名は絶対名として解釈されます。ゾーン外部のドメイン名を指定する時は、常に絶対名を指定します。

例えばドメイン名に www.example.net. を指定した時、ゾーンに関わらず www.example.net. に解決されます。

相対名

末尾がドットで終わらないドメイン名はゾーン内部の相対名として解釈されます。

例えば example.net. ゾーン内でドメイン名に www を指定した時、 www.example.net. に解決されます。

Zone Apex

ドメイン名に @ を単独で指定した時、 Zone Apex として解釈されます。

例えば example.net. ゾーン内でドメイン名に @ を指定した時、 example.net. に解決されます。

A リソースレコード¶

{
  "name": "example.net.",
  "type": "A",
  "enable_alias": false,
  "ttl": 3600,
  "records": [
    {
      "address": "192.0.2.10"
    }
  ]
}

プロパティ	型	説明
.records[].address	string	IPv4 アドレス

NS リソースレコード¶

{
  "name": "example.net.",
  "type": "NS",
  "enable_alias": false,
  "ttl": 86400,
  "records": [
    {
      "nsdname": "ns2.gehirndns.com."
    },
    {
      "nsdname": "ns2.example.jp."
    },
    {
      "nsdname": "ns2.example.net."
    },
    {
      "nsdname": "ns2.example.org."
    }
  ]
}

プロパティ	型	説明
.records[].nsdname	string	ネームサーバーのドメインネーム

CNAME リソースレコード¶

{
  "name": "example.net.",
  "type": "CNAME",
  "enable_alias": false,
  "ttl": 86400,
  "records": [
    {
      "cname": "cname.example.org."
    }
  ]
}

プロパティ	型	説明
.records[].cname	string	CNAME

CNAME の注意点¶

CNAME はほかのドメイン名の「別名」を設定するためのリソースタイプです。このため、 DNS の仕様を定めた RFC1034 により以下の制約があります。

.records[] 配列の要素は常に 1 つみ許可されます。
Zone Apex に作成することはできません。
- Zone Apex に CNAME を指定したい場合は、エイリアスのご利用をご検討ください。
ひとつのドメイン名においてほかのリソースタイプと共存することができません。

つまり、 www IN A と www IN CNAME を同時に作成することはできません。 CNAME が関係しない www IN A と www IN AAAA は同時に作成することができます。

MX リソースレコード¶

{
  "name": "example.net.",
  "type": "MX",
  "enable_alias": false,
  "ttl": 86400,
  "records": [
    {
      "prio": 10,
      "exchange": "mx1.mta.gis.gehirn.jp."
    },
    {
      "prio": 10,
      "exchange": "mx2.mta.gis.gehirn.jp."
    },
    {
      "prio": 10,
      "exchange": "mx3.mta.gis.gehirn.jp."
    },
    {
      "prio": 10,
      "exchange": "mx4.mta.gis.gehirn.jp."
    },
    {
      "prio": 10,
      "exchange": "mx5.mta.gis.gehirn.jp."
    }
  ]
}

プロパティ	型	説明
.records[].prio	integer	優先度
.records[].exchange	string	メールエクスチェンジのドメインネーム

TXT リソースレコード¶

{
  "name": "example.net.",
  "type": "TXT",
  "enable_alias": false,
  "ttl": 86400,
  "records": [
    {
      "data": "v=spf1 +include:_spf.gehirn.jp -all"
    }
  ]
}

プロパティ	型	説明
.records[].data	string	TXT データ

AAAA リソースレコード¶

{
  "name": "example.net.",
  "type": "AAAA",
  "enable_alias": false,
  "ttl": 3600,
  "records": [
    {
      "address": "2001:db8::10"
    }
  ]
}

プロパティ	型	説明
.records[].address	string	IPv6 アドレス

SRV リソースレコード¶

{
  "name": "_submission._tcp.example.net.",
  "type": "SRV",
  "enable_alias": false,
  "ttl": 86400,
  "records": [
    {
      "prio": 10,
      "weight": 0,
      "target": "mx.mta.gis.gehirn.jp.",
      "port": 587
    }
  ]
}

プロパティ	型	説明
.records[].prio	integer	優先度
.records[].weight	integer	ウェイト
.records[].target	string	ターゲットのドメインネーム
.records[].port	integer	ポート番号

SVCB/HTTPS リソースレコード¶

{
  "name": "example.net.",
  "type": "HTTPS",
  "enable_alias": false,
  "ttl": 3600,
  "records": [
    {
      "prio": 1,
      "target": ".",
      "params": {
        "alpn": "h2,h3"
      }
    }
  ]
}

プロパティ

型

要否

説明

.records[].prio

integer

必須

優先度

.records[].target

string

必須

ターゲットのドメインネーム

.records[].params

object<string, string>

任意

SVCB パラメーター

パラメーターキーは以下のいずれか

mandatory
alpn
no-default-alpn
port
ipv4hint
ech
ipv6hint
keyNNNNN 形式

CAA リソースレコード¶

{
  "name": "example.net.",
  "type": "CAA",
  "enable_alias": false,
  "ttl": 3600,
  "records": [
    {
      "flags": 0,
      "tag": "issue",
      "value": "pki.example.org."
    }
  ]
}

プロパティ	型	説明
.records[].flags	integer	フラグ
.records[].tag	string	タグ
.records[].value	string	値

エイリアス¶

Gehirn DNS では、指定したドメイン名を解決した結果のリソースレコードを応答するエイリアス機能を提供しています。

DNS の仕様上 Zone Apex で CNAME を使用することはできませんが、エイリアス機能を利用することで CNAME に似た機能を Zone Apex でも実現しています。

エイリアス機能は、 CNAME Flattening などとも呼ばれます。

なお、 A または AAAA 以外のリソースタイプでエイリアス機能を利用することは非推奨になりました。また、ゾーン内でエイリアス機能を利用することもリソースタイプに関わらず推奨していません。

{
  "name": "example.net.",
  "type": "A",
  "enable_alias": true,
  "alias_to": "www.example.org."
}

エイリアス代替手段¶

用途	代替手段
MX	値を直接ご入力ください。 `.records[].exchange` に共通の名前を指定することで、その名前の A/AAAA リソースレコードを一度更新するだけでメールサーバーの IP アドレスを一斉に切り替えることができます。
TXT (DKIM)	CNAME をご利用ください。 DKIM は `default._domainkey` のような公開鍵ごとに固有のオーナーネームを使用するため、常に CNAME で代替することができます。
TXT (SPF)	SPF 標準の `include` ディレクティブまたは `redirect` 修飾子をご利用ください。例: `v=spf1 +include:_spf.gehirn.jp -all`
SRV	値を直接ご入力ください。 SRV リソースレコードは `_service._proto` 形式の固有のオーナーネームを使用するため、 CNAME で代替することができます。また、 `.records[].target` に CNAME を指定することもできます。

JSON Schema¶

レコードオブジェクト全体の JSON Schema は以下の通りです。

{
  "definitions": {
    "uint16": {
      "type": "integer",
      "minimum": 0,
      "maximum": 65535
    },
    "hostname": {
      "type": "string",
      "minLength": 1,
      "maxLength": 254
    },
    "ipv4address": {
      "type": "string",
      "minLength": 7,
      "maxLength": 15
    },
    "ipv6address": {
      "type": "string",
      "minLength": 2,
      "maxLength": 39
    }
  },
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 36,
      "readOnly": true
    },
    "name": { "$ref": "#/definitions/hostname" },
    "type": {
      "enum": [
        "A",
        "NS",
        "CNAME",
        "MX",
        "TXT",
        "AAAA",
        "SRV",
        "SVCB",
        "HTTPS",
        "CAA"
      ]
    },
    "enable_alias": { "type": "boolean" },
    "alias_to": { "$ref": "#/definitions/hostname" },
    "ttl": {
      "type": "integer",
      "minimum": 30,
      "maximum": 2147483647
    },
    "records": {
      "type": "array",
      "minItems": 1,
      "maxItems": 25,
      "oneOf": [
        {
          "items": {
            "title": "A / AAAA",
            "type": "object",
            "properties": {
              "address": {
                "anyOf": [
                  { "$ref": "#/definitions/ipv4address" },
                  { "$ref": "#/definitions/ipv6address" }
                ]
              }
            },
            "required": ["address"],
            "additionalProperties": false
          }
        },
        {
          "items": {
            "title": "NS",
            "type": "object",
            "properties": {
              "nsdname": { "$ref": "#/definitions/hostname" }
            },
            "required": ["nsdname"],
            "additionalProperties": false
          }
        },
        {
          "items": {
            "title": "CNAME",
            "type": "object",
            "properties": {
              "cname": { "$ref": "#/definitions/hostname" }
            },
            "required": ["cname"],
            "additionalProperties": false
          }
        },
        {
          "items": {
            "title": "MX",
            "type": "object",
            "properties": {
              "prio": { "$ref": "#/definitions/uint16" },
              "exchange": { "$ref": "#/definitions/hostname" }
            },
            "required": ["prio", "exchange"],
            "additionalProperties": false
          }
        },
        {
          "items": {
            "title": "TXT",
            "type": "object",
            "properties": {
              "data": {
                "type": "string",
                "minLength": 1,
                "maxLength": 4000
              }
            },
            "required": ["data"],
            "additionalProperties": false
          }
        },
        {
          "items": {
            "title": "SRV",
            "type": "object",
            "properties": {
              "prio": { "$ref": "#/definitions/uint16" },
              "weight": { "$ref": "#/definitions/uint16" },
              "target": { "$ref": "#/definitions/hostname" },
              "port": { "$ref": "#/definitions/uint16" }
            },
            "required": ["prio", "weight", "target", "port"],
            "additionalProperties": false
          }
        },
        {
          "items": {
            "title": "SVCB / HTTPS",
            "type": "object",
            "properties": {
              "prio": { "$ref": "#/definitions/uint16" },
              "target": { "$ref": "#/definitions/hostname" },
              "params": {
                "type": "object",
                "properties": {
                  "mandatory": { "type": "string" },
                  "alpn": { "type": "string" },
                  "no-default-alpn": { "type": "string" },
                  "port": { "type": "string" },
                  "ipv4hint": { "type": "string" },
                  "ech": { "type": "string" },
                  "ipv6hint": { "type": "string" }
                },
                "patternProperties": {
                  "^type(0|[1-9][0-9]{0,4})$": { "type": "string" }
                },
                "additionalProperties": false
              }
            },
            "required": ["prio", "target"],
            "additionalProperties": false
          }
        },
        {
          "items": {
            "title": "CAA",
            "type": "object",
            "properties": {
              "flags": {
                "type": "integer",
                "minimum": 0,
                "maximum": 255
              },
              "tag": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255
              },
              "value": { "type": "string" }
            },
            "required": ["flags", "tag", "value"],
            "additionalProperties": false
          }
        }
      ]
    }
  },
  "oneOf": [
    { "required": ["name", "type", "enable_alias", "ttl", "records"] },
    { "required": ["name", "type", "enable_alias", "alias_to"] }
  ],
  "additionalProperties": false
}

ドメイン名とリソースタイプによるレコード指定方法¶

以下で説明する操作のうち、作成・取得・編集・削除は HTTP リクエストパスにレコード ID の代わりに操作対象のドメイン名とリソースタイプを指定することもできます。

この方法ではレコードの一覧から操作対象の ID を特定する必要がなく、直接レコード作成・編集・削除することができます。このため、例えば Gehirn DNS を DDNS のように利用する場合などに活用できます。

リクエストパス¶

/dns/v1/zones/{zone_id}/versions/{version_id}/records/{domain_name}/IN/{record_type}

パスパラメーター¶
パラメーター	値
zone_id	レコードが存在するゾーンの ID
version_id	レコードが存在するバージョンの ID
domain_name	リソースレコードの名前ここで指定するドメイン名は FQDN である必要があります。相対名や @ を指定することはできません。また、 PUT リクエストではリクエストボディの .name と一致する必要があります
resource_type	リソースレコードのタイプ PUT リクエストではリクエストボディの .type と一致する必要があります

HTTP メソッド¶
HTTP メソッド	効果
GET	レコードを取得します。存在しない場合は HTTP 404 エラーが応答されます。
PUT	レコードを作成または編集します。指定されたレコードが存在しない場合は新たに作成し、存在する場合は編集します。
DELETE	レコードを削除します。存在しない場合は HTTP 404 エラーが応答されます。

作成・編集リクエスト例¶

PUT /dns/v1/zones/:zone_id/versions/:version_id/records/example.net./IN/A HTTP/1.1
Host: api.gis.gehirn.jp
Content-Type: application/json

{
  "name": "example.net.",
  "type": "A",
  "enable_alias": false,
  "ttl": 3600,
  "records": [
    {
      "address": "192.0.2.10"
    }
  ]
}

作成¶

指定したバージョンに新しいレコードを追加します。

ドメイン名とリソースタイプによるレコード指定方法もご利用になれます。

HTTP リクエスト¶

POST /dns/v1/zones/:zone_id/versions/:version_id/records HTTP/1.1
Host: api.gis.gehirn.jp
Content-Type: application/json

{
  "name": "example.net.",
  "type": "A",
  "enable_alias": false,
  "ttl": 3600,
  "records": [
    {
      "address": "192.0.2.10"
    }
  ]
}

パスパラメーター¶
パラメーター	値
zone_id	レコードを追加するゾーンの ID
version_id	レコードを追加するバージョンの ID

リクエストボディ¶

追加したいレコードオブジェクトをリクエストしてください。

HTTP レスポンス¶

追加されたレコードオブジェクトが返ります。

一覧¶

指定したバージョンに存在するすべてのレコードを取得します。

HTTP リクエスト¶

GET /dns/v1/zones/:zone_id/versions/:version_id/records HTTP/1.1
Host: api.gis.gehirn.jp

パラメーター¶

パラメーター	値
zone_id	取得するレコードを含むゾーンの ID
version_id	取得するレコードを含むバージョンの ID

リクエストボディ¶

リクエストボディは必要ありません。

HTTP レスポンス¶

ひとつ以上のレコードオブジェクトを含む JSON array が返ります。

取得¶

指定したバージョンに存在する個別のレコードを取得します。

ドメイン名とリソースタイプによるレコード指定方法もご利用になれます。

HTTP リクエスト¶

GET /dns/v1/zones/:zone_id/versions/:version_id/records/:record_id HTTP/1.1
Host: api.gis.gehirn.jp

パスパラメーター¶
パラメーター	値
zone_id	取得するレコードを含むゾーンの ID
version_id	取得するレコードを含むバージョンの ID
record_id	取得するレコードの ID

リクエストボディ¶

リクエストボディは必要ありません。

HTTP レスポンス¶

指定したレコードオブジェクトが返ります。

編集¶

指定したバージョンに存在する個別のレコードを編集します。

ドメイン名とリソースタイプによるレコード指定方法もご利用になれます。

HTTP リクエスト¶

PUT /dns/v1/zones/:zone_id/versions/:version_id/records/:record_id HTTP/1.1
Host: api.gis.gehirn.jp

リクエストパラメータ¶

パラメーター	値
zone_id	編集するレコードを含むゾーンの ID
version_id	編集するレコードを含むバージョンの ID
record_id	編集するレコードの ID

リクエストボディ¶

編集したレコードオブジェクトをリクエストしてください。

HTTP レスポンス¶

編集されたレコードオブジェクトが返ります。

削除¶

指定したバージョンから個別のレコードを削除します。

ドメイン名とリソースタイプによるレコード指定方法もご利用になれます。

HTTP リクエスト¶

DELETE /dns/v1/zones/:zone_id/versions/:version_id/records/:record_id HTTP/1.1
Host: api.gis.gehirn.jp

パラメーター¶

パラメーター	値
zone_id	削除するレコードを含むゾーンの ID
version_id	削除するレコードを含むバージョンの ID
record_id	削除するレコードの ID

ドメイン名とリソースタイプによるレコード指定方法もご利用になれます。

リクエストボディ¶

リクエストボディは必要ありません。

HTTP レスポンス¶

削除されたレコードオブジェクトが返ります。