データ API ビルダーで REST エンドポイントをホストする

[アーティクル]
12/19/2024

データ API ビルダーには、接続されたデータベースからテーブル、ビュー、ストアドプロシージャにアクセスできる RESTful Web API が用意されています。エンティティは、データ API ビルダーのランタイム構成のデータベースオブジェクトを表します。 REST API エンドポイントでエンティティを使用できるようにするには、ランタイム構成でエンティティを設定する必要があります。

REST API メソッドを呼び出す

リソース (またはエンティティ) の読み取りまたは書き込みを行うには、次のパターンを使用して要求を作成します。

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

手記

エンティティやクエリパラメーターを含む URL パスのすべてのコンポーネントでは、大文字と小文字が区別されます。

要求のコンポーネントは次のとおりです。

	形容
`{HTTP method}`	データ API ビルダーへの要求で使用される HTTP メソッド
`{base_url}`	データ API ビルダーのインスタンスをホストするドメイン (または localhost サーバーとポート)
`{rest-path}`	ランタイム構成で設定された REST API エンドポイントのベースパス
`{entity}`	ランタイム構成で定義されているデータベースオブジェクトの名前

ローカル開発環境 localhostの REST エンドポイントベース /api の下に存在する book エンティティに対する GET 要求の例を次に示します。

GET https:/localhost:5001/api/Book

HTTP メソッド

データ API ビルダーは、要求で HTTP メソッドを使用して、要求指定エンティティに対して実行するアクションを決定します。特定のエンティティに設定されているアクセス許可に応じて、次の HTTP 動詞を使用できます。

方式	形容
`GET`	0 個、1 つ以上の項目を取得する
`POST`	新しい項目を作成する
`PATCH`	項目が存在する場合は、新しい値で更新します。それ以外の場合は、新しい項目を作成します
`PUT`	項目が存在する場合は、新しい項目に置き換えます。それ以外の場合は、新しい項目を作成します
`DELETE`	アイテムを削除する

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"
    }
  ]
}

手記

既定では、最初の 100 個の項目のみが返されます。

取得

GET メソッドを使用すると、目的のエンティティの 1 つ以上の項目を取得できます。

URL パラメーター

REST エンドポイントを使用すると、URL パラメーターを使用して主キーで項目を取得できます。 1 つの主キーを持つエンティティの場合、形式は簡単です。

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

1001の ID を持つ書籍を取得するには、次の値を使用します。

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

手記

要求されたフィールドのいずれかが存在しないか、アクセス許可が構成されているためにアクセスできない場合は、400 - Bad Request が返されます。

$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 オプションでサポートされる演算子は次のとおりです。

演算子	種類	形容	例
`eq`	比較	等しい	`title eq 'Hyperion'`
`ne`	比較	等しくない	`title ne 'Hyperion'`
`gt`	比較	より大きい	`year gt 1990`
`ge`	比較	以上	`year ge 1990`
`lt`	比較	未満	`year lt 1990`
`le`	比較	以下	`year le 1990`
`and`	合理的	論理と	`year ge 1980 and year lt 1990`
`or`	合理的	論理または	`year le 1960 or title eq 'Hyperion'`
`not`	合理的	論理否定	`not (year le 1960)`
`( )`	グルーピング	優先順位のグループ化	`(year ge 1970 or title eq 'Foundation') and pages gt 400`

手記

$filter は、大文字と小文字を区別する引数です。

Azure Data API Builder の $filter クエリパラメーターは、一部のユーザーに OData を思い出させる可能性があります。これは、OData のフィルター処理機能に直接着想を得たためです。構文はほぼ同じであるため、OData に既に慣れている開発者は簡単に取得して使用できます。この類似性は意図的なもので、さまざまな API でデータをフィルター処理するための使い慣れた強力な方法を提供することを目的としています。

`$orderby`

orderby パラメーターの値は、項目の並べ替えに使用される式のコンマ区切りのリストです。

orderby パラメーター値の各式には、式から 1 つ以上のスペースで区切られた降順を要求するサフィックス 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 は、大文字と小文字を区別する引数です。

$orderby クエリパラメーターは、サーバー上でデータを直接並べ替える場合に便利で、クライアント側でも簡単に処理できます。ただし、$filter や $firstなど、他のクエリパラメーターと組み合わせると便利になります。このパラメーターを使用すると、大規模なコレクションをページングするときに、ページ分割によって安定した予測可能なデータセットを維持できます。

`$first` と `$after`

$first クエリパラメーターは、1 つの要求で返される項目の数を制限します。例えば：

GET /api/book?$first=5

この要求は、最初の 5 冊の書籍を返します。 Azure Data API Builder の $first クエリパラメーターは、SQL の TOP 句に似ています。どちらも、クエリから返されるレコードの数を制限するために使用されます。 SQL の TOP で取得する行の数を指定できるのと同様に、$first API によって返される項目の数を制御できます。 $first は、データセット全体を取得せずに、最初の 10 件の結果などのデータの小さなサブセットをフェッチする場合に便利です。主な利点は、送信および処理されるデータの量を減らすため、効率です。

手記

Azure Data API ビルダーでは、既定で返される行数は、構成ファイルの設定によって制限されます。ユーザーは、$first パラメーターを使用してこの制限をオーバーライドして、より多くの行を要求できますが、全体的に返すことができる行の最大数は引き続き構成されています。さらに、1 つの応答で返すことができる合計メガバイト数には制限があり、構成も可能です。

指定した制限を超えて使用できる項目が増えた場合、応答には 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 要求によって新しい書籍が作成されます。 null 許容にできないすべてのフィールドを指定する必要があります。成功した場合、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) で失敗します。ヘッダーが省略場合、既定の動作では、アップサートが実行され、リソースがまだ存在しない場合に作成されます。

例:

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

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

手記

If-Match ヘッダーに * 以外の値を指定した場合、ETag ベースの照合はサポートされていないため、データ API ビルダーは 400 Bad Request エラーを返します。

パッチ

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 要求ヘッダー

例:

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 ビルダーは、トランザクション内でデータベースクエリを構築して実行します。

次の表に、データベースの種類ごとにトランザクションを作成する分離レベルを示します。

データベースの種類	分離レベル	詳細情報
Azure SQL (または) SQL Server	Read Committed	Azure SQL
MySQL	反復可能読み取り	MySQL
PostgreSQL	Read Committed	PostgreSQL

次の方法で共有

データ API ビルダーで REST エンドポイントをホストする

REST API メソッドを呼び出す

HTTP メソッド

Rest パス

実体

結果セットの形式

取得

URL パラメーター

例えば：

クエリパラメーター

`$select`

`$filter`

`$orderby`

`$first` と `$after`

投稿

置く

`If-Match: *` HTTP 要求ヘッダー

パッチ

`If-Match: *` HTTP 要求ヘッダー

削除

REST API 要求のデータベーストランザクション

フィードバック

その他のリソース

次の方法で共有

データ API ビルダーで REST エンドポイントをホストする

REST API メソッドを呼び出す

HTTP メソッド

Rest パス

実体

結果セットの形式

取得

URL パラメーター

例えば：

クエリ パラメーター

$select

$filter

$orderby

$first と $after

投稿

置く

If-Match: * HTTP 要求ヘッダー

パッチ

If-Match: * HTTP 要求ヘッダー

削除

REST API 要求のデータベース トランザクション

関連コンテンツ

フィードバック

その他のリソース

クエリパラメーター

`$select`

`$filter`

`$orderby`

`$first` と `$after`

`If-Match: *` HTTP 要求ヘッダー

`If-Match: *` HTTP 要求ヘッダー

REST API 要求のデータベーストランザクション