요청 및 응답 API 트랜잭션
변경 제안
PDF
모든 배포 API 호출은 클라이언트에 대한 관련 응답을 생성하는 배포 가상 시스템에 대한 HTTP 요청으로 수행됩니다. 이 요청/응답 쌍은 API 트랜잭션으로 간주됩니다. Deploy API를 사용하기 전에 요청을 제어하는 데 사용할 수 있는 입력 변수와 응답 출력의 내용을 숙지해야 합니다.
API 요청을 제어하는 입력 변수입니다
HTTP 요청에 설정된 매개 변수를 통해 API 호출 처리 방법을 제어할 수 있습니다.
요청 헤더
HTTP 요청에 다음과 같은 여러 헤더를 포함해야 합니다.
-
content-type 요청 본문에 JSON이 포함되어 있으면 이 헤더를 application/json으로 설정해야 합니다.
-
수락 응답 본문에 JSON이 포함될 경우 이 헤더를 application/json으로 설정해야 합니다.
-
권한 부여 기본 인증은 base64 문자열로 인코딩된 사용자 이름과 암호로 설정되어야 합니다.
요청 본문
요청 본문의 내용은 특정 호출에 따라 달라집니다. HTTP 요청 본문은 다음 중 하나로 구성됩니다.
-
입력 변수가 있는 JSON 개체(예: 새 클러스터의 이름)
-
비어 있습니다
개체를 필터링합니다
Get을 사용하는 API 호출을 실행할 때 모든 특성에 따라 반환된 객체를 제한하거나 필터링할 수 있습니다. 예를 들어, 다음과 같이 정확하게 일치하는 값을 지정할 수 있습니다.
<field>=<query value>
정확한 일치 항목 외에 값 범위에 있는 개체 집합을 반환할 수 있는 다른 연산자도 있습니다. ONTAP Select는 아래 표시된 필터링 연산자를 지원합니다.
| 운영자 | 설명 |
|---|---|
= |
같음 |
를 누릅니다 |
보다 작음 |
를 누릅니다 |
보다 큼 |
lt;=.(&L |
보다 작거나 같음 |
GT;=.(&T |
보다 크거나 같음 |
또는 |
|
! |
같지 않음 |
* |
greedy 와일드카드 |
또한 쿼리의 일부로 Null 키워드 또는 해당 부정(!null)을 사용하여 특정 필드가 설정되었는지 여부를 기준으로 개체 집합을 반환할 수도 있습니다.
개체 필드 선택
기본적으로 Get 을 사용하여 API 호출을 실행하면 개체나 개체를 고유하게 식별하는 특성만 반환됩니다. 이 최소 필드 집합은 각 개체의 키 역할을 하며 개체 유형에 따라 달라집니다. 다음과 같은 방법으로 필드 쿼리 매개 변수를 사용하여 추가 개체 속성을 선택할 수 있습니다.
-
저렴한 필드는
fields=*로컬 서버 메모리에 유지되거나 액세스 처리가 거의 필요하지 않은 개체 필드를 검색하도록 지정합니다. -
값비싼 필드는
fields=**액세스를 위해 추가 서버 처리가 필요한 필드를 포함하여 모든 개체 필드를 검색하도록 지정합니다. -
사용자 정의 필드 선택 을 사용하여
fields=FIELDNAME원하는 정확한 필드를 지정합니다. 여러 필드를 요청할 때는 공백 없이 쉼표를 사용하여 값을 구분해야 합니다.
|
가장 좋은 방법은 항상 원하는 특정 필드를 식별하는 것입니다. 필요한 경우 저렴한 필드나 값비싼 필드 집합만 검색해야 합니다. 저렴하고 값비싼 분류는 내부 성능 분석을 기반으로 NetApp에서 결정합니다. 지정된 필드의 분류는 언제든지 변경할 수 있습니다. |
출력 집합에서 개체를 정렬합니다
리소스 컬렉션의 레코드는 개체에서 정의한 기본 순서로 반환됩니다. 다음과 같이 필드 이름 및 정렬 방향이 있는 ORDER_BY 쿼리 매개 변수를 사용하여 순서를 변경할 수 있습니다.
order_by=<field name> asc|desc
예를 들어 다음과 같이 형식 필드를 내림차순으로 정렬한 다음 ID를 오름차순으로 정렬할 수 있습니다.
order_by=type desc, id asc
여러 매개 변수를 포함할 때는 필드를 쉼표로 구분해야 합니다.
페이지 매김
Get 을 사용하여 API 호출을 실행하면 동일한 형식의 개체 컬렉션에 액세스할 때 일치하는 모든 개체가 기본적으로 반환됩니다. 필요한 경우 요청과 함께 max_records 쿼리 매개 변수를 사용하여 반환되는 레코드 수를 제한할 수 있습니다. 예를 들면 다음과 같습니다.
max_records=20
필요한 경우 이 매개 변수를 다른 쿼리 매개 변수와 결합하여 결과 집합의 범위를 좁힐 수 있습니다. 예를 들어, 다음과 같이 지정된 시간 이후에 생성된 최대 10개의 시스템 이벤트를 반환합니다.
time⇒ 2019-04-04T15:41:29.140265Z&max_records=10
이벤트(또는 모든 개체 유형)를 통해 페이지를 넘도록 여러 요청을 실행할 수 있습니다. 이후의 각 API 호출은 마지막 결과 집합의 최신 이벤트를 기반으로 새 시간 값을 사용해야 합니다.
API 응답을 해석합니다
각 API 요청은 클라이언트에 대한 응답을 다시 생성합니다. 응답을 검토하여 성공 여부를 확인하고 필요에 따라 추가 데이터를 검색할 수 있습니다.
HTTP 상태 코드입니다
Deploy REST API에 사용되는 HTTP 상태 코드는 아래와 같다.
| 코드 | 의미 | 설명 |
|---|---|---|
200 |
좋습니다 |
새 개체를 만들지 않는 호출에 대한 성공 여부를 나타냅니다. |
201 |
작성됨 |
객체가 성공적으로 생성되었습니다. 위치 응답 헤더에는 객체의 고유 식별자가 포함됩니다. |
202 |
수락됨 |
요청을 수행하기 위해 오래 실행되는 백그라운드 작업이 시작되었지만 작업이 아직 완료되지 않았습니다. |
400 |
잘못된 요청입니다 |
요청 입력이 인식되지 않거나 부적절합니다. |
403 |
금지됨 |
인증 오류로 인해 액세스가 거부되었습니다. |
404 |
찾을 수 없습니다 |
요청에서 참조되는 리소스가 없습니다. |
405 |
메서드가 허용되지 않습니다 |
요청의 HTTP 동사는 리소스에 대해 지원되지 않습니다. |
409 |
충돌 |
개체가 이미 있으므로 개체를 만들지 못했습니다. |
500 |
내부 오류입니다 |
서버에서 일반적인 내부 오류가 발생했습니다. |
501 |
구현되지 않았습니다 |
URI를 알고 있지만 요청을 수행할 수 없습니다. |
응답 헤더
배포 서버에서 생성된 HTTP 응답에는 다음과 같은 여러 헤더가 포함됩니다.
-
Request-id 성공한 모든 API 요청에는 고유한 요청 식별자가 할당됩니다.
-
위치 개체를 만들 때 위치 머리글에는 고유한 개체 식별자를 포함하여 새 개체에 대한 전체 URL이 포함됩니다.
응답 바디
API 요청과 관련된 응답 내용은 객체, 처리 유형 및 요청의 성공 또는 실패에 따라 달라집니다. 응답 본문은 JSON으로 렌더링됩니다.
-
단일 개체 단일 개체는 요청에 따라 필드 집합과 함께 반환할 수 있습니다. 예를 들어, 가져오기를 사용하여 고유 식별자를 사용하여 클러스터의 선택된 속성을 검색할 수 있습니다.
-
여러 개체 리소스 컬렉션의 여러 개체를 반환할 수 있습니다. 모든 경우에 개체 인스턴스의 배열을 포함하는 레코드 및 레코드 수를 나타내는 일관된 형식이
num_records사용됩니다. 예를 들어, 특정 클러스터에 정의된 모든 노드를 검색할 수 있습니다. -
작업 개체 API 호출이 비동기적으로 처리되는 경우 백그라운드 작업을 고정한 작업 개체가 반환됩니다. 예를 들어, 클러스터를 배포하는 데 사용되는 POST 요청은 비동기적으로 처리되고 작업 개체를 반환합니다.
-
오류 개체 오류가 발생하면 오류 개체는 항상 반환됩니다. 예를 들어, 이름이 이미 존재하는 클러스터를 생성하려고 하면 오류가 발생합니다.
-
비어 있는 경우 데이터가 반환되지 않고 응답 본문이 비어 있는 경우가 있습니다. 예를 들어, 삭제 기능을 사용하여 기존 호스트를 삭제한 후 응답 본문이 비어 있습니다.