Entities

データベース エンティティの構成設定。

Health

Source

REST

GraphQL

Permissions

Relationships

Cache

Format overview

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <boolean> // default: true
        "path": <string> // default: "{entity-name}"
        "methods": ["GET", "POST"] // default: ["GET", "POST"]
      },
      "graphql": {
        "enabled": <boolean> // default: true
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" | "mutation" // default: "query"
      },
      "source": {
        "object": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // primary keys for the view
        "parameters": { // only for stored-procedure
          "<parameter-name>": <string | number | boolean>,
          "<parameter-name>": <string | number | boolean>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": <string>,
          "source.fields": [<string>],
          "target.fields": [<string>],
          "linking.object": <string>,
          "linking.source.fields": [<string>],
          "linking.target.fields": [<string>]
        }
      },
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | <custom-role>,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": [<string>],
            "exclude": [<string>]
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

ソース (エンティティ名エンティティ)

エンティティのデータベース ソースの詳細。

Nested properties

• key-fields は、 type が viewされている場合にのみ必要です。 値は主キーを表します。

** parameters は、 type が stored-procedureされている場合にのみ必要です。 省略可能なパラメーターは省略できます。

サポートされているパラメーター データ型:

1. string—ANSI と Unicode が含まれます。JSON/Date/DateTime 型にも使用されます
2. number—整数と 10 進数を含む
3. boolean—true または false

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // primary keys of the view
        "parameters": { // only for stored-procedure
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>
        }
      }
    }
  }
}

アクセス許可 (エンティティ名エンティティ)

アクセス許可が適用されるロールの名前を指定する文字列。

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">
        }
      ]
    }
  }
}

Example

この例では、User エンティティに対するreadアクセス許可のみを持つロール custom-roleを定義します。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "custom-role",
          "actions": ["read"]
        }
      ]
    }
  }
}

Usage examples

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");
// To read the response content:
// var content = await response.Content.ReadAsStringAsync();

const response = await fetch('https://localhost:5001/api/User', {
  headers: {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});
// To read the response body as JSON:
// const data = await response.json();

import requests

headers = {
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
# To print the response JSON:
print(response.json())

アクション (string-array Permissions エンティティ名エンティティ)

関連付けられているロールに対して許可される操作の詳細を示す文字列配列。

* 現在、複数の操作は GraphQL でのみサポートされています。

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

代替形式 ( type=stored-procedureの場合は文字列のみ)

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

アクション (object-array Permissions エンティティ名エンティティ)

関連付けられたロールに対して許可される操作の詳細を示すオブジェクト配列。

Nested properties

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": <array of strings>,
              "policy": <object>
            }
          ]
        }
      ]
    }
  }

Example

これによりreadフィールドとポリシーの制限を使用して、User エンティティにauditorするアクセス許可が付与されます。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Policy notes

• ポリシーでは、 eqなどの OData 演算子がサポートされます。
• ポリシーでは、 and と orを使用した複合述語がサポートされます。
• アクション ( create、 read、 update、 delete) でのみサポートされます。 ( executeではありません)
• ポリシーは結果をフィルター処理しますが、データベースでのクエリの実行を妨げることはありません。
• フィールドがマップされている場合は、フィールドエイリアスを使用する必要があります。

型 (GraphQL エンティティ名エンティティ)

GraphQL スキーマ内のエンティティの名前付け規則を設定します。

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "type": {
          "singular": "<string>",
          "plural": "<string>"
        }
      }
    }
  }
}

Nested properties

Example

Configuration

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

GraphQL query

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

GraphQL response

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

操作 (GraphQL エンティティ名エンティティ)

QueryまたはMutationの下にstored-procedure操作を表示するかどうかを指定します。

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

Example: operation

operationが に設定されている場合query

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

operationが に設定されている場合mutation

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

有効 (GraphQL エンティティ名エンティティ)

開発者が GraphQL スキーマにエンティティを選択的に含めることができます。

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

REST (エンティティ名エンティティ)

* methods プロパティは、 stored-procedure エンドポイント専用です。

Format

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "{entity-name}">
      }
    }
  }
}

マッピング (エンティティ名エンティティ)

データベース オブジェクト フィールドのカスタム エイリアスまたは公開名を有効にします。

Format

{
  "entities": {
    "{entity-name}": {
      "mappings": {
        "<field-1-name>": "<field-1-alias>",
        "<field-2-name>": "<field-2-alias>",
        "<field-3-name>": "<field-3-alias>"
      }
    }
  }
}

Examples

Database Table

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

Configuration

{
  "entities": {
    "Books": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

キャッシュ (エンティティ名エンティティ)

エンティティのキャッシュを有効にして構成します。

Nested properties

Format

{
  "entities": {
    "{entity-name}": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>
      }
    }
  }
}

Example

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30
      }
    }
  }
}

リレーションシップ (エンティティ名エンティティ)

GraphQL エンティティを他の公開エンティティと関連付ける方法を構成します。 詳細については、「データ API ビルダーのリレーションシップの内訳を参照してください。

Nested properties

これらのプロパティは、リレーションシップのカーディナリティに応じて異なる組み合わせで使用されます。

Format

{
  "entities": {
    "{entity-name}": {
      "relationships": {
        "<relationship-name>": {
          "cardinality": "one" | "many",
          "target.entity": "<string>",
          "source.fields": ["<string>"],
          "target.fields": ["<string>"],
          "linking.object": "<string>",
          "linking.source.fields": ["<string>"],
          "linking.target.fields": ["<string>"]
        }
      }
    }
  }
}

例: 1 対 1 のカーディナリティ

各 Profile は正確に 1 つの Userに関連しており、各 User には 1 つの関連 Profileがあります。

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

GraphQL schema

type User
{
  id: Int!
  ...
  profile: Profile
}

Command-line

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

例: 一対多カーディナリティ

Categoryには 1 つ以上の関連するBook エンティティを含めることができますが、各Bookには 1 つの関連するCategoryを含めることができます。

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

GraphQL schema

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

Command line

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

例: 多対一カーディナリティ

多くの Book エンティティは、1 つの関連する Categoryを持つことができますが、 Category には 1 つ以上の関連する Book エントリを含めることができます。

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

GraphQL schema

type Book
{
  id: Int!
  ...
  category: Category
}

Command line

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

例: 多対多カーディナリティ

多くの Book エンティティには多くの関連 Author エンティティを含めることができますが、多くの Author エンティティには多くの関連する Book エントリを含めることができます。

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

GraphQL schema

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

Command line

dab update Book \
  --relationship books_authors \
  --target.entity "Author" \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

正常性 (エンティティ名エンティティ)

エンティティの正常性チェックを有効にして構成します。

Nested properties

Format

{
  "entities": {
    "{entity-name}": {
      "health": {
        "enabled": true,
        "first": 5,
        "threshold-ms": 2000
      }
    }
  }
}

Example

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}