batchUpdateRecords

이 가이드는 API 명세를 기반으로 자동 생성했습니다.

Classic/VPC 환경에서 이용 가능합니다.

Ncloud API 표준 규격을 적용한 API입니다.

레코드를 일괄 수정합니다. 각 레코드는 전체 교체(full-replace)로 처리되며, 요청에서 생략된 비필수 필드(aliasNo, loadBalancerNo, loadBalancerRegionCode 등)는 기존 값이 유지되지 않고 null로 초기화됩니다. 따라서 클라이언트는 각 레코드의 원하는 전체 표현을 그대로 전송해야 합니다. 한 번에 최대 500건까지 처리할 수 있으며, 초과 시 400 InvalidParameter 로 응답합니다. 요청 항목이 하나라도 실패하면 전체가 처리되지 않으며, 실패한 항목만 failures 에 요청 인덱스로 지목해 반환합니다. 실패 원인이 존재하지 않는 레코드 번호뿐이면 404 ResourceNotFound, 항목 검증 실패(형식·값 오류)가 섞여 있으면 400 으로 응답합니다. defaultRecord 가 true 인 시스템 관리 레코드는 수정할 수 없습니다. apex SOA·DS 레코드는 모든 필드를 수정할 수 없고, apex NS 레코드는 ttl 만 수정할 수 있어 그 밖의 필드를 바꾸려 하면 400 InvalidOperation 으로 거부됩니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
POST	/domains/{domainNo}/records/batch-update

요청 헤더

Global DNS API에서 공통으로 사용하는 헤더에 대한 정보는 Global DNS 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`domainNo`	Integer (int64)	Required	도메인 번호 보유하지 않았거나 존재하지 않는 번호는 403 Forbidden (두 경우를 구분하지 않음) <예시> 120

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`records`	List<RecordUpdateRequest>	Required	수정할 레코드 목록 항목 수: 1 ~ 500

RecordUpdateRequest

일괄 수정(batch-update) 요청의 항목. 대상을 지목해야 하므로 공용 본문에 recordNo 를 더한 형태이며, 단건 수정은 path 의 recordNo 로 대상을 지정하므로 이 스키마를 쓰지 않습니다.

필드	타입	필수 여부	설명
`host`	String	Optional	레코드 호스트 (도메인 기준 상대 이름) 도메인 자체(apex)는 빈 문자열 또는 `@` 로 지정하며, 생략해도 apex 로 처리 apex 로 지정한 레코드는 응답의 `host` 에 `@` 로 표기 각 라벨은 1~63바이트의 영문·숫자·하이픈 (하이픈으로 시작·종료 불가) 와일드카드 `` 는 라벨 전체로만 사용 가능 host 와 도메인 이름을 합친 FQDN 이 253바이트 이하여야 하므로, 실제 최대 길이는 도메인 이름 길이에 따라 다름 패턴: `^$\\|^@$\\|^(\\\|[A-Za-z0-9]([A-Za-z0-9-][A-Za-z0-9])?)(\.(\\\|[A-Za-z0-9]([A-Za-z0-9-][A-Za-z0-9])?))$` 길이: ~ 253 <예시> www
`type`	String	Required	레코드 타입 SOA 와 DNSSEC 관련 타입(DNSKEY·NSEC3·RRSIG)은 시스템이 관리하므로 지정 불가 NS·DS 는 하위 도메인 위임 용도로만 지정 가능 (apex 불가) `A` \| `AAAA` \| `CAA` \| `CNAME` \| `DS` \| `MX` \| `NS` \| `PTR` \| `SPF` \| `SRV` \| `TXT` <예시> A
`content`	String	Required	레코드 값 (형식은 `type` 에 따라 다름) A: IPv4 주소 AAAA: IPv6 주소 CNAME·NS·PTR: 도메인 이름 MX: `우선순위 대상도메인` SRV: `우선순위 가중치 포트 대상도메인` DS: `키태그 알고리즘 다이제스트타입 다이제스트` 형식의 값 2개를 줄바꿈(`\n`)으로 구분해 한 레코드로 지정 (2개가 아니면 400 InvalidParameter) 한 레코드에 값 여러 개를 지정할 때는 줄바꿈(`\n`)으로 구분 (CNAME 은 1개만 가능) 길이 상한은 TXT·SPF 가 64,000바이트이며, 그 밖의 타입은 타입별 형식 검증이 결정 길이는 바이트 기준으로 검증하므로, 멀티바이트 문자로 채운 값은 길이 제약을 만족해도 거부될 수 있음 형식 위반·길이 초과는 400 InvalidParameter 의 `fieldErrors` 로 항목별 사유 반환 길이: ~ 64,000 <예시> 10.0.0.1
`ttl`	Integer (int64)	Required	TTL (초) 범위: 0 ~ 2,147,483,647 <예시> 300
`aliasNo`	Integer (int64) \| null	Optional	연결할 별칭 번호 별칭 레코드를 만들 때만 지정 (일반 레코드는 생략하거나 null) `loadBalancerNo` 와 동시 지정 불가 <예시> 700
`loadBalancerNo`	Integer (int64) \| null	Optional	연결할 로드밸런서 번호 `GET /record-linkable-load-balancers` 응답의 `loadBalancerNo` 값 사용 지정할 때는 `loadBalancerRegionCode` 도 함께 지정 로드밸런서를 연결하지 않는 레코드는 생략하거나 null `aliasNo` 와 동시 지정 불가 <예시> 900
`loadBalancerRegionCode`	LoadBalancerRegionCode \| Null	Optional	연결할 로드밸런서의 리전 코드 `loadBalancerNo` 를 지정할 때만 사용 로드밸런서를 조회한 리전과 같은 값 <예시> KR
`recordNo`	Integer (int64)	Required	대상 레코드 번호 <예시> 5001

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://globaldns.apigw.gov-ntruss.com/dns/v2/domains/120/records/batch-update' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
  "records": [
    {
      "type": "A",
      "content": "10.0.0.1",
      "ttl": 300,
      "recordNo": 5001
    }
  ]
}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`results`	Map<RecordResponse>	-	요청 인덱스별 생성/수정된 레코드 자원 맵 <예시> {"0": {"domainNo": 120, "domainName": "example.com", "recordNo": 5001, "host": "www", "name": "www.example.com", "type": "A", "content": "10.0.0.1", "ttl": 300, "aliasNo": null, "pendingDeletion": false, "createdTimestamp": 1568111263000, "updatedTimestamp": 1568111263000, "applied": true, "defaultRecord": false, "loadBalancerNo": null, "loadBalancerRegionCode": null}, "1": {"domainNo": 120, "domainName": "example.com", "recordNo": 5002, "host": "api", "name": "api.example.com", "type": "A", "content": "10.0.0.2", "ttl": 300, "aliasNo": null, "pendingDeletion": false, "createdTimestamp": 1568111263000, "updatedTimestamp": 1568111263000, "applied": true, "defaultRecord": false, "loadBalancerNo": null, "loadBalancerRegionCode": null}}

RecordResponse

레코드 상세

필드	타입	필수 여부	설명
`domainNo`	Integer (int64)	-	레코드가 속한 도메인의 번호 <예시> 120
`domainName`	String	-	도메인 이름 <예시> example.com
`recordNo`	Integer (int64)	-	레코드 번호 <예시> 5001
`host`	String	-	레코드 호스트 (도메인 기준 상대 이름) 도메인 자체(apex)는 `@` 로 표기 <예시> www
`name`	String	-	레코드 이름 (FQDN) <예시> www.example.com
`type`	String	-	레코드 타입 `A` \| `AAAA` \| `CAA` \| `CNAME` \| `DS` \| `MX` \| `NS` \| `PTR` \| `SOA` \| `SPF` \| `SRV` \| `TXT` \| `DNSKEY` \| `NSEC3` \| `RRSIG` <예시> A
`content`	String	-	레코드 값(content) 값이 여러 개인 레코드는 줄바꿈(`\n`)으로 구분 <예시> 10.0.0.1
`ttl`	Integer (int64)	-	TTL (초) <예시> 300
`aliasNo`	Integer (int64) \| null	-	별칭 번호 (별칭 레코드가 아니면 null) <예시> 700
`pendingDeletion`	Boolean	-	레코드 삭제 대기 여부 `true` \| `false` <예시> false
`createdTimestamp`	Integer (int64)	-	생성 시각 (Unix epoch 밀리초) <예시> 1568111263000
`updatedTimestamp`	Integer (int64)	-	수정 시각 (Unix epoch 밀리초) <예시> 1568111263000
`applied`	Boolean	-	네임서버 적용 여부 `true` \| `false` `true`: 변경 내용이 네임서버에 적용됨 `false`: 생성·수정·삭제 후 아직 적용 전 <예시> true
`defaultRecord`	Boolean	-	기본 레코드 여부 기본 레코드는 삭제 불가 (400 CannotDelete) 기본 레코드 중 SOA·DS 는 수정 불가, NS 는 `ttl` 만 수정 가능 (그 밖의 수정은 400 InvalidOperation) `true` \| `false` `true`: 도메인 이름과 같은 이름(apex)의 SOA·NS·DS 레코드. 시스템이 관리하며 도메인 삭제 시 함께 정리 `false`: 사용자가 생성한 레코드 <예시> false
`loadBalancerNo`	Integer (int64) \| null	-	로드밸런서 번호 (로드밸런서 레코드가 아니면 null) <예시> 900
`loadBalancerRegionCode`	LoadBalancerRegionCode \| Null	-	로드밸런서 리전 코드 (로드밸런서 레코드가 아니면 null) <예시> KR

응답 상태 코드

Global DNS API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Global DNS 응답 상태 코드를 참조해 주십시오.

이 API에만 해당하는 응답 상태 코드는 다음과 같습니다.

HTTP 상태 코드	코드	메시지	설명
200	-	-	OK
400	InvalidOperation	The specified operation is invalid.	`defaultRecord` 가 true 인 시스템 관리 레코드를 수정하려 한 경우(apex SOA·DS 는 수정 불가, apex NS 는 `ttl` 외 수정 불가). 일괄 수정에서는 해당 항목의 요청 인덱스가 `failures` 에 지목됨. 수정 가능한 필드만 변경하거나 해당 항목을 제외하고 다시 요청
404	ResourceNotFound	The specified resource could not be found.	요청한 레코드 번호나 작업 ID가 존재하지 않는 경우(완료 후 30일 보관 기간이 지나 삭제된 작업 포함). 일괄 수정·삭제에서는 실패 원인이 미존재뿐일 때 반환하며 해당 항목의 요청 인덱스가 `failures` 에 지목됨. 목록을 조회해 번호·ID를 확인한 뒤 다시 요청

응답 예시

응답 예시는 다음과 같습니다.

{
  "results": {
    "0": {
      "domainNo": 120,
      "domainName": "example.com",
      "recordNo": 5001,
      "host": "www",
      "name": "www.example.com",
      "type": "A",
      "content": "10.0.0.1",
      "ttl": 300,
      "aliasNo": null,
      "pendingDeletion": false,
      "createdTimestamp": 1568111263000,
      "updatedTimestamp": 1568111263000,
      "applied": true,
      "defaultRecord": false,
      "loadBalancerNo": null,
      "loadBalancerRegionCode": null
    },
    "1": {
      "domainNo": 120,
      "domainName": "example.com",
      "recordNo": 5002,
      "host": "api",
      "name": "api.example.com",
      "type": "A",
      "content": "10.0.0.2",
      "ttl": 300,
      "aliasNo": null,
      "pendingDeletion": false,
      "createdTimestamp": 1568111263000,
      "updatedTimestamp": 1568111263000,
      "applied": true,
      "defaultRecord": false,
      "loadBalancerNo": null,
      "loadBalancerRegionCode": null
    }
  }
}