ONTAP Select에 대한 요청 및 응답 API 트랜잭션
변경 제안
PDF
모든 Deploy API 호출은 Deploy 가상 머신에 대한 HTTP 요청으로 수행되며, 가상 머신은 이에 대한 응답을 클라이언트로 전송합니다. 이러한 요청/응답 쌍을 API 트랜잭션이라고 합니다. Deploy API를 사용하기 전에 요청을 제어하는 데 사용할 수 있는 입력 변수와 응답 출력 내용을 숙지해야 합니다.
API 요청을 제어하는 입력 변수
HTTP 요청에 설정된 매개변수를 통해 API 호출 처리 방식을 제어할 수 있습니다.
요청 헤더
다음을 포함한 여러 헤더를 HTTP 요청에 포함해야 합니다.
-
content-type 요청 본문에 JSON이 포함된 경우 이 헤더는 application/json으로 설정해야 합니다.
-
accept 응답 본문에 JSON이 포함될 경우, 이 헤더는 application/json으로 설정해야 합니다.
-
authorization 기본 인증은 base64 문자열로 인코딩된 사용자 이름과 비밀번호로 설정해야 합니다.
요청 본문
요청 본문의 내용은 특정 호출에 따라 다릅니다. HTTP 요청 본문은 다음 중 하나로 구성됩니다.
-
입력 변수(예: 새 클러스터의 이름)가 포함된 JSON 객체
-
비어 있음
객체 필터링
GET을 사용하는 API 호출을 실행할 때 모든 속성을 기반으로 반환된 객체를 제한하거나 필터링할 수 있습니다. 예를 들어 일치시킬 정확한 값을 지정할 수 있습니다.
<field>=<query value>
정확히 일치하는 항목 외에도, 특정 값 범위에 걸쳐 객체 집합을 반환하는 데 사용할 수 있는 다른 연산자가 있습니다. ONTAP Select는 아래에 표시된 필터링 연산자를 지원합니다.
| 운영자 | 설명 |
|---|---|
= |
같음 |
< |
미만 |
> |
보다 큼 |
⇐ |
이하 |
>= |
크거나 같음 |
또는 |
|
! |
같지 않음 |
* |
탐욕적 와일드카드 |
쿼리의 일부로 null 키워드 또는 그 부정형(!null)을 사용하면 특정 필드가 설정되었는지 여부에 따라 객체 집합을 반환할 수도 있습니다.
객체 필드 선택
기본적으로 GET을 사용하여 API 호출을 실행하면 객체를 고유하게 식별하는 속성만 반환됩니다. 이러한 최소 필드 집합은 각 객체의 키 역할을 하며 객체 유형에 따라 다릅니다. 다음과 같은 방법으로 fields 쿼리 매개변수를 사용하여 추가 객체 속성을 선택할 수 있습니다.
-
비용이 저렴한 필드 `fields=*`를 지정하여 로컬 서버 메모리에 유지되거나 액세스하는 데 처리량이 거의 필요하지 않은 객체 필드를 검색합니다.
-
비용이 많이 드는 필드 `fields=**`를 지정하면 액세스하는 데 추가 서버 처리가 필요한 필드를 포함하여 모든 객체 필드를 검색합니다.
-
사용자 지정 필드 선택 `fields=FIELDNAME`을 사용하여 원하는 필드를 정확하게 지정할 수 있습니다. 여러 필드를 요청할 경우 값은 공백 없이 쉼표로 구분해야 합니다.
|
모범 사례로, 항상 원하는 특정 필드를 식별해야 합니다. 필요할 때만 저렴한 필드 또는 비싼 필드 세트를 가져오십시오. 저렴한 필드와 비싼 필드 분류는 NetApp의 내부 성능 분석을 기반으로 결정됩니다. 특정 필드에 대한 분류는 언제든지 변경될 수 있습니다. |
출력 세트의 객체를 정렬합니다
리소스 컬렉션의 레코드는 객체에 정의된 기본 순서대로 반환됩니다. 다음과 같이 필드 이름과 정렬 방향을 지정하여 order_by 쿼리 매개변수를 사용하면 순서를 변경할 수 있습니다:
order_by=<field name> asc|desc
예를 들어, type 필드를 내림차순으로 정렬한 다음 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 |
OK |
새 객체를 생성하지 않는 호출이 성공했음을 나타냅니다. |
201 |
생성됨 |
객체가 성공적으로 생성되었습니다. 위치 응답 헤더에 해당 객체의 고유 식별자가 포함되어 있습니다. |
202 |
수락됨 |
요청을 처리하기 위해 장시간 실행되는 백그라운드 작업이 시작되었지만, 아직 작업이 완료되지 않았습니다. |
400 |
잘못된 요청 |
요청 입력값이 인식되지 않거나 부적절합니다. |
403 |
금지됨 |
권한 오류로 인해 액세스가 거부되었습니다. |
404 |
찾을 수 없음 |
요청에서 참조한 리소스가 존재하지 않습니다. |
405 |
메서드가 허용되지 않습니다 |
요청에 사용된 HTTP 동사는 해당 리소스에서 지원되지 않습니다. |
409 |
충돌 |
객체가 이미 존재하므로 객체를 생성하지 못했습니다. |
500 |
내부 오류 |
서버에서 일반적인 내부 오류가 발생했습니다. |
501 |
구현되지 않음 |
URI는 알려져 있지만 요청을 수행할 수 없습니다. |
응답 헤더
Deploy 서버에서 생성되는 HTTP 응답에는 다음과 같은 여러 헤더가 포함됩니다.
-
request-id 모든 성공적인 API 요청에는 고유한 요청 식별자가 할당됩니다.
-
location 객체가 생성될 때 location 헤더에는 고유한 객체 식별자를 포함하여 새 객체의 전체 URL이 포함됩니다.
응답 본문
API 요청과 관련된 응답의 내용은 객체, 처리 유형 및 요청의 성공 또는 실패에 따라 다릅니다. 응답 본문은 JSON으로 렌더링됩니다.
-
단일 객체 단일 객체는 요청에 따라 필드 집합과 함께 반환될 수 있습니다. 예를 들어, GET을 사용하여 고유 식별자를 통해 클러스터의 선택된 속성을 검색할 수 있습니다.
-
여러 객체 리소스 컬렉션에서 여러 객체를 반환할 수 있습니다. 모든 경우에 일관된 형식이 사용되며, `num_records`레코드 수와 객체 인스턴스 배열을 포함하는 레코드가 표시됩니다. 예를 들어 특정 클러스터에 정의된 모든 노드를 검색할 수 있습니다.
-
Job 객체 API 호출이 비동기적으로 처리되는 경우 백그라운드 작업을 고정하는 Job 객체가 반환됩니다. 예를 들어, 클러스터를 배포하는 데 사용되는 POST 요청은 비동기적으로 처리되며 Job 객체를 반환합니다.
-
Error 객체 오류가 발생하면 항상 Error 객체가 반환됩니다. 예를 들어, 이미 존재하는 이름으로 클러스터를 생성하려고 하면 오류가 발생합니다.
-
비어 있음 특정 경우에는 데이터가 반환되지 않고 응답 본문이 비어 있습니다. 예를 들어, DELETE를 사용하여 기존 호스트를 삭제한 후에는 응답 본문이 비어 있습니다.