Data API 작성기에서 REST 엔드포인트 호스트

데이터 API 작성기에서는 연결된 데이터베이스에서 테이블, 뷰 및 저장 프로시저에 액세스할 수 있는 RESTful 웹 API를 제공합니다. 엔터티는 Data API Builder의 런타임 구성에서 데이터베이스 개체를 나타냅니다. REST API 엔드포인트에서 엔터티를 사용할 수 있도록 런타임 구성에서 엔터티를 설정해야 합니다.

REST API 메서드 호출

리소스(또는 엔터티)에서 읽거나 쓰려면 다음 패턴을 사용하여 요청을 생성합니다.

{HTTP method} https://{base_url}/{rest-path}/{entity}

요청의 구성 요소는 다음과 같습니다.

다음은 로컬 개발 환경 localhost의 REST 엔드포인트 기본 URL /api 아래에 있는 book 엔터티에 대한 GET 요청 예시입니다.

GET https:/localhost:5001/api/Book

HTTP 메서드

데이터 API 작성기에서 요청의 HTTP 메서드를 사용하여 요청 지정된 엔터티에 대해 수행할 작업을 결정합니다. 특정 엔터티에 대해 설정된 사용 권한에 따라 다음 HTTP 동사를 사용할 수 있습니다.

Rest 경로

나머지 경로는 데이터 API 작성기의 REST API 위치를 지정합니다. 경로는 런타임 구성에서 구성할 수 있으며 기본적으로 /api. 자세한 내용은 REST 경로 구성참조하세요.

실체

엔터티 데이터 API 작성기에서 REST API 리소스를 참조하는 데 사용되는 용어입니다. 기본적으로 엔터티의 URL 경로 값은 런타임 구성에 정의된 엔터티 이름입니다. 엔터티의 REST URL 경로 값은 엔터티의 REST 설정 내에서 구성할 수 있습니다. 자세한 내용은 엔터티 구성를 참조하세요.

결과 집합 형식

반환된 결과는 다음 형식의 JSON 개체입니다.

{
    "value": []    
}

요청된 엔터티와 관련된 항목은 value 배열에서 사용할 수 있습니다. 예를 들어:

{
  "value": [
    {
      "id": 1000,
      "title": "Foundation"
    },
    {
      "id": 1001,
      "title": "Foundation and Empire"
    }
  ]
}

가져오기

GET 메서드를 사용하여 원하는 엔터티의 항목을 하나 이상 검색할 수 있습니다.

URL 매개 변수

REST 엔드포인트를 사용하면 URL 매개 변수를 사용하여 기본 키로 항목을 검색할 수 있습니다. 단일 기본 키가 있는 엔터티의 경우 형식은 간단합니다.

GET /api/{entity}/{primary-key-column}/{primary-key-value}

ID가 1001인 책을 조회하려면 다음을 사용해야 합니다.

GET /api/book/id/1001

레코드를 고유하게 식별하는 데 둘 이상의 열이 사용되는 복합 기본 키가 있는 엔터티의 경우 URL 형식에는 모든 키 열이 순서대로 포함됩니다.

GET /api/{entity}/{primary-key-column1}/{primary-key-value1}/{primary-key-column2}/{primary-key-value2}

books 엔터티에 id1 및 id2으로 구성된 복합 키가 있는 경우 다음과 같은 특정 책을 검색할 수 있습니다.

GET /api/books/id1/123/id2/abc

예를 들어:

통화의 모양은 다음과 같습니다.

### Retrieve a book by a single primary key
GET /api/book/id/1001

### Retrieve an author by a single primary key
GET /api/author/id/501

### Retrieve a book by compound primary keys (id1 and id2)
GET /api/books/id1/123/id2/abc

### Retrieve an order by compound primary keys (orderId and customerId)
GET /api/orders/orderId/789/customerId/456

### Retrieve a product by compound primary keys (categoryId and productId)
GET /api/products/categoryId/electronics/productId/987

### Retrieve a course by compound primary keys (departmentCode and courseNumber)
GET /api/courses/departmentCode/CS/courseNumber/101

쿼리 매개 변수

REST 엔드포인트는 반환된 항목을 제어하기 위해 다음 쿼리 매개 변수(대/소문자 구분)를 지원합니다.

• $select: 선택한 열만 반환합니다.
• $filter: 반환된 항목을 필터링합니다.
• $orderby: 반환된 데이터를 정렬하는 방법을 정의합니다.
• $first 및 $after: 상위 n 항목만 반환합니다.

쿼리 매개 변수를 함께 사용할 수 있습니다.

$select

쿼리 매개 변수 $select 반환해야 하는 필드를 지정할 수 있습니다. 예를 들어:

### Get all fields
GET /api/author

### Get only first_name field
GET /api/author?$select=first_name

### Get only first_name and last_name fields
GET /api/author?$select=first_name,last_name

"프로젝션"이라고도 하는 $select 쿼리 매개 변수는 API 응답에서 반환되는 데이터의 크기를 제어하는 데 사용됩니다. 필요한 열만 사용하면 $select 페이로드 크기를 줄여 구문 분석 시간을 최소화하고 대역폭 사용량을 줄이며 데이터 처리 속도를 높여 성능을 향상시킬 수 있습니다. 이 최적화는 데이터베이스로 확장됩니다. 요청된 열만 검색됩니다.

$filter

$filter 옵션의 값은 엔터티의 필드를 사용하는 조건자 식(부울 결과를 반환하는 식)입니다. 식이 True로 평가되는 항목만 응답에 포함됩니다. 예를 들어:

### Get books titled "Hyperion" (Equal to)
GET /api/book?$filter=title eq 'Hyperion'

### Get books not titled "Hyperion" (Not equal to)
GET /api/book?$filter=title ne 'Hyperion'

### Get books published after 1990 (Greater than)
GET /api/book?$filter=year gt 1990

### Get books published in or after 1990 (Greater than or equal to)
GET /api/book?$filter=year ge 1990

### Get books published before 1991 (Less than)
GET /api/book?$filter=year lt 1991

### Get books published in or before 1990 (Less than or equal to)
GET /api/book?$filter=year le 1990

### Get books published between 1980 and 1990 (Logical and)
GET /api/book?$filter=year ge 1980 and year le 1990

### Get books published before 1960 or titled "Hyperion" (Logical or)
GET /api/book?$filter=year le 1960 or title eq 'Hyperion'

### Get books not published before 1960 (Logical negation)
GET /api/book?$filter=not (year le 1960)

### Get books published in 1970 or later, and either titled "Foundation" or with more than 400 pages (Grouping)
GET /api/book?$filter=(year ge 1970 or title eq 'Foundation') and pages gt 400

$filter 옵션에서 지원하는 연산자는 다음과 같습니다.

Azure Data API Builder의 $filter 쿼리 매개 변수는 일부 사용자에게 OData를 상기시킬 수 있으며 이는 OData의 필터링 기능에서 직접 영감을 받았기 때문입니다. 구문은 거의 동일하므로 OData에 이미 익숙한 개발자가 쉽게 선택하고 사용할 수 있습니다. 이러한 유사성은 여러 API에서 데이터를 필터링하는 친숙하고 강력한 방법을 제공하기 위한 의도적인 것이었습니다.

$orderby

orderby 매개 변수의 값은 항목을 정렬하는 데 사용되는 쉼표로 구분된 식 목록입니다.

orderby 매개변수 값의 각 표현식은 내림차순으로 정렬하기 위한 접미사 desc을 하나 이상의 공백으로 표현식과 구분하여 포함할 수 있습니다.

예를 들어:

### Order books by title in ascending order
GET /api/book?$orderby=title

### Order books by title in ascending order
GET /api/book?$orderby=title asc

### Order books by title in descending order
GET /api/book?$orderby=title desc

### Order books by year of publication in ascending order, then by title in ascending order
GET /api/book?$orderby=year asc, title asc

### Order books by year of publication in descending order, then by title in ascending order
GET /api/book?$orderby=year desc, title asc

### Order books by number of pages in ascending order, then by title in descending order
GET /api/book?$orderby=pages asc, title desc

### Order books by title in ascending order, then by year of publication in descending order
GET /api/book?$orderby=title asc, year desc

$orderby 쿼리 매개 변수는 클라이언트 쪽에서도 쉽게 처리할 수 있는 서버에서 직접 데이터를 정렬하는 데 유용합니다. 그러나 $filter 및 $first같은 다른 쿼리 매개 변수와 결합하면 유용합니다. 이 매개 변수를 사용하면 큰 컬렉션을 페이지를 매길 때 페이지 매김이 안정적이고 예측 가능한 데이터 세트를 유지할 수 있습니다.

$first 및 $after

$first 쿼리 매개 변수는 단일 요청에서 반환되는 항목 수를 제한합니다. 예를 들어:

GET /api/book?$first=5

이 요청은 처음 다섯 권의 책을 반환합니다. Azure Data API Builder의 $first 쿼리 매개 변수는 SQL의 TOP 절과 유사합니다. 둘 다 쿼리에서 반환되는 레코드 수를 제한하는 데 사용됩니다. SQL의 TOP 검색할 행의 수량을 지정할 수 있는 것처럼 $first API에서 반환되는 항목 수를 제어할 수 있습니다. $first 전체 데이터 세트를 검색하지 않고 처음 10개 결과와 같은 작은 데이터 하위 집합을 가져오려는 경우에 유용합니다. 가장 큰 장점은 전송 및 처리되는 데이터의 양을 줄이기 때문에 효율성입니다.

지정된 한도를 초과하여 더 많은 항목을 사용할 수 있는 경우 응답에는 nextLink 속성이 포함됩니다.

{
    "value": [],
    "nextLink": "dab-will-generate-this-continuation-url"
}

nextLink $after 쿼리 매개 변수와 함께 사용하여 다음 항목 집합을 검색할 수 있습니다.

GET /api/book?$first={n}&$after={continuation-data}

이 연속 방법은 커서 기반 페이지 매김을 사용합니다. 고유한 커서는 데이터 세트의 특정 항목에 대한 참조로, 다음 집합에서 데이터를 계속 검색할 위치를 결정합니다. 오프셋 또는 인덱스를 사용하는 인덱스 페이지 매김과 달리 커서 기반 페이지 매김은 레코드 건너뛰기를 사용하지 않습니다. 커서 연속을 사용하면 대용량 데이터 세트 또는 자주 변경되는 데이터로 더 안정적입니다. 대신 제공된 커서에 따라 마지막 쿼리가 중단된 위치를 정확하게 시작하여 데이터 검색의 원활하고 일관된 흐름을 보장합니다.

예를 들어:

### Get the first 5 books explicitly
GET /api/book?$first=5

### Get the next set of 5 books using the continuation token
GET /api/book?$first=5&$after={continuation-token}

### Get the first 10 books, ordered by title
GET /api/book?$first=10&$orderby=title asc

### Get the next set of 10 books after the first set, ordered by title
GET /api/book?$first=10&$after={continuation-token}&$orderby=title asc

### Get books without specifying $first (automatic pagination limit)
GET /api/book

### Get the next set of books using the continuation token without specifying $first
GET /api/book?$after={continuation-token}

올리기

지정된 엔터티에 대한 새 항목을 만듭니다. 예를 들어:

POST /api/book
Content-type: application/json

{
  "id": 2000,
  "title": "Do Androids Dream of Electric Sheep?"
}

POST 요청은 새 책을 만듭니다. nullable이 될 수 없는 모든 필드를 제공해야 합니다. 성공하면 null 필드를 포함한 전체 엔터티 개체가 반환됩니다.

{
  "value": [
    {
      "id": 2000,
      "title": "Do Androids Dream of Electric Sheep?",
      "year": null,
      "pages": null
    }
  ]
}

놓다

PUT은 지정된 엔터티의 항목을 만들거나 바꿉니다. 쿼리 패턴은 다음과 같습니다.

PUT /api/{entity}/{primary-key-column}/{primary-key-value}

예를 들어:

PUT /api/book/id/2001
Content-type: application/json

{  
  "title": "Stranger in a Strange Land",
  "pages": 525
}

지정된 기본 키 2001을 가진 항목이 있는 경우, 제공된 데이터 이 해당 항목을 완전히 바꿉니다. 대신 해당 기본 키가 있는 항목이 없으면 새 항목이 만들어집니다.

두 경우 모두 결과는 다음과 같습니다.

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": null,
      "pages": 525
    }
  ]
}

If-Match: * HTTP 요청 헤더

HTTP 헤더 리소스가경우에만 업데이트 작업 수행되도록 합니다. 리소스가 없으면 HTTP 상태 코드404 Not Found와 함께 작업이 실패합니다. 헤더가생략되지 경우 기본 동작은 아직 없는 경우 리소스를 만드는 upsert수행하는 것입니다.

예제:

PUT /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
  "title": "Stranger in a Strange Land",
  "pages": 525
}

패치

PATCH는 지정된 엔터티의 항목을 만들거나 업데이트합니다. 지정된 필드만 영향을 받습니다. 요청 본문에 지정되지 않은 모든 필드는 영향을 받지 않습니다. 지정된 기본 키가 있는 항목이 없으면 새 항목이 만들어집니다.

쿼리 패턴은 다음과 같습니다.

PATCH /api/{entity}/{primary-key-column}/{primary-key-value}

예를 들어:

PATCH /api/book/id/2001
Content-type: application/json

{    
  "year": 1991
}

결과는 다음과 같습니다.

{
  "value": [
    {
      "id": 2001,
      "title": "Stranger in a Strange Land",
      "year": 1991,
      "pages": 525
    }
  ]
}

If-Match: * HTTP 요청 헤더

HTTP 헤더 리소스가경우에만 업데이트 작업 수행되도록 합니다. 리소스가 없으면 HTTP 상태 코드404 Not Found와 함께 작업이 실패합니다. 헤더가생략되지 경우 기본 동작은 아직 없는 경우 리소스를 만드는 upsert수행하는 것입니다.

예제:

PATCH /api/Books/2001 HTTP/1.1
If-Match: *
Content-Type: application/json

{
    "year": 1991
}

삭제하다

DELETE는 지정된 엔터티의 항목을 삭제합니다. 쿼리 패턴은 다음과 같습니다.

DELETE /api/{entity}/{primary-key-column}/{primary-key-value}

예를 들어:

DELETE /api/book/id/2001

성공하면 결과는 상태 코드 204가 포함된 빈 응답입니다.

REST API 요청에 대한 데이터베이스 트랜잭션

POST, PUT, PATCH 및 DELETE API 요청을 처리하려면 데이터 API 작성기에서는 트랜잭션에서 데이터베이스 쿼리를 생성하고 실행합니다.

다음 표에서는 각 데이터베이스 유형에 대해 트랜잭션이 만들어지는 격리 수준을 나열합니다.

관련 콘텐츠

• OpenAPI
• REST 구성 참조