データ API ビルダー構成スキーマ リファレンス

データ API ビルダーのエンジンには構成ファイルが必要です。 Data API Builder 構成ファイルには、API を設定するための構造化された包括的なアプローチが用意されており、環境変数からエンティティ固有の構成まで、すべてを詳しく説明します。 この JSON 形式のドキュメントは、$schema プロパティで始まります。 このセットアップでは、ドキュメントが検証されます。

プロパティ database-type および connection-string により、Azure SQL Database から Cosmos DB NoSQL API へのデータベース システムとのシームレスな統合が保証されます。

構成ファイルには、次のようなオプションを含めることができます。

• データベース サービスと接続情報
• グローバル構成オプションとランタイム構成オプション
• 公開されたエンティティのセット
• 認証方法
• ID にアクセスするために必要なセキュリティ規則
• API とデータベース間の名前マッピング規則
• 推論できないエンティティ間のリレーションシップ
• 特定のデータベース サービスに固有の機能

構文の概要

構成ファイルのプライマリ "セクション" の簡単な内訳を次に示します。

{
  "$schema": "...",
  "data-source": { ... },
  "data-source-files": [ ... ],
  "runtime": {
    "rest": { ... },
    "graphql": { .. },
    "host": { ... },
    "cache": { ... },
    "telemetry": { ... },
    "pagination": { ... }
  }
  "entities": [ ... ]
}

最上位のプロパティ

テーブル形式の最上位のプロパティの説明を次に示します。

構成のサンプル

1 つの単純なエンティティに必要なプロパティのみを含むサンプル構成ファイルを次に示します。 このサンプルは、最小限のシナリオを示すことを目的としています。

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

より複雑なシナリオの例については、エンド ツー エンドのサンプル構成を参照してください。

環境

データ API ビルダーの構成ファイルは、ASP.NET Core の appSettings.json ファイルと同様に、複数の環境をサポートする必要があるシナリオをサポートできます。 フレームワークは、3 つの 共通の環境値を提供します。、、および ;ただし、選択した任意の環境値を使用することもできます。 データ API ビルダーが使用する環境は、DAB_ENVIRONMENT 環境変数を使用して構成する必要があります。

ベースライン構成と開発固有の構成が必要な例を考えてみましょう。 この例では、次の 2 つの構成ファイルが必要です。

開発固有の構成を使用するには、DAB_ENVIRONMENT 環境変数を Developmentに設定する必要があります。

環境固有の構成ファイルは、基本構成ファイルのプロパティ値をオーバーライドします。 この例では、両方のファイルで connection-string 値が設定されている場合、*.Development.json ファイルの値が使用されます。

どちらのファイルでどの値が指定されているか (指定されていないか) に応じて、どの値が使用されるかを理解するには、このマトリックスを参照してください。

複数の構成ファイルを使用する例については、環境でデータ API ビルダー 使用する方法に関するページを参照してください。

構成プロパティ

このセクションには、構成ファイルで使用できるすべての構成プロパティが含まれています。

スキーマ

各構成ファイルは プロパティで始まり、検証に JSON スキーマを指定します。

形式

{
  "$schema": <string>
}

例

スキーマ ファイルは、特定の URL 0.3.7-alpha 以降のバージョンで使用でき、正しいバージョンまたは使用可能な最新のスキーマを使用していることを確認します。

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

VERSION-suffix を目的のバージョンに置き換えます。

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

スキーマの最新バージョンは常に https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.jsonで使用できます。

有効なスキーマ値の例をいくつか次に示します。

データ ソース

data-source セクションでは、接続文字列を使用してデータベースとデータベースへのアクセスを定義します。 また、データベース オプションも定義します。 data-source プロパティは、バッキング データベースに接続するために必要な資格情報を構成します。 data-source セクションでは、database-type と connection-stringの両方を指定して、バックエンド データベース接続の概要を示します。

形式

{
  "data-source": {
    "database-type": <string>,
    "connection-string": <string>,
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": <string>,
      "container": <string>,
      "schema": <string>
    }
  }
}

プロパティ

データベースの種類

データ ソースとして使用するデータベースの種類を指定するために使用される列挙型文字列。

形式

{
  "data-source": {
    "database-type": <string>
  }
}

型の値

type プロパティは、バックエンド データベースの種類を示します。

接続文字列

ターゲット データベース サービスに接続するための有効な接続文字列を含む 文字列 値です。 バックエンド データベースに接続する ADO.NET 接続文字列。 詳細については、「接続文字列ADO.NET する」を参照してください。

形式

{
  "data-source": {
    "connection-string": <string>
  }
}

接続の回復性

データ API ビルダーは、一時的なエラーを検出した後、データベース要求を自動的に再試行します。 再試行ロジックは、再試行の最大数が 5指数バックオフ 戦略に従います。 後続の要求後の再試行バックオフ期間は、この数式を使用して計算されます (現在の再試行が rであると仮定): $r^2$

この数式を使用すると、再試行の各時間を秒単位で計算できます。

Azure SQL と SQL Server

データ API ビルダーは、SqlClient ライブラリを使用して、構成ファイルに指定した接続文字列を使用して Azure SQL または SQL Server に接続します。 サポートされているすべての接続文字列オプションの一覧は、SqlConnection.ConnectionString プロパティです。

データ API ビルダーは、データ API ビルダーが Azure でホストされている場合に、マネージド サービス ID (MSI) を使用してターゲット データベースに接続することもできます。 DefaultAzureCredential ライブラリで定義されている Azure.Identity は、接続文字列でユーザー名またはパスワードを指定しない場合に、既知の ID を使用して接続するために使用されます。 詳細については、 例を参照してください。

• ユーザー割り当てマネージド ID (UMI): ユーザー割り当てマネージド ID のクライアント ID () に置き換えながら、認証 と Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>; プロパティを接続文字列に追加します。
• システム割り当てマネージド ID (SMI): Authentication プロパティを追加し、接続文字列から UserId 引数と Password 引数を除外します:Authentication=Active Directory Managed Identity;。 UserId と パスワード 接続文字列プロパティがない場合、DAB はシステム割り当てマネージド ID を使用して認証するように通知します。

Azure SQL または SQL Server を使用したマネージド サービス ID の構成の詳細については、「Microsoft Entra for Azure SQLでのマネージド ID の 」を参照してください。

例

接続文字列に使用される値は、シナリオで使用されるデータベース サービスによって大きく異なります。 接続文字列はいつでも環境変数に格納し、@env() 関数を使用してアクセスできます。

これらのサンプルは、各データベースの種類の構成方法を示しています。 シナリオは一意である可能性がありますが、このサンプルは出発点として適しています。 myserver、myDataBase、mylogin、myPassword などのプレースホルダーを、実際の環境に固有の値に置き換えます。

mssql

"data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}

postgresql

"data-source": {
  "database-type": "postgresql",
  "connection-string": "$env('my-connection-string')"
}

mysql

"data-source": {
  "database-type": "mysql",
  "connection-string": "$env('my-connection-string')"
}

cosmosdb_nosql

"data-source": {
  "database-type": "cosmosdb_nosql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "database": "Your_CosmosDB_Database_Name",
    "container": "Your_CosmosDB_Container_Name",
    "schema": "Path_to_Your_GraphQL_Schema_File"
  }
}

cosmosdb_postgresql

"data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}

オプション

特定のデータベース接続用の追加のキー値パラメーターの省略可能なセクション。

options セクションが必要かどうかは、使用されているデータベース サービスに大きく依存します。

形式

{
  "data-source": {
    "options": {
      "<key-name>": <string>
    }
  }
}

options: { set-session-context: boolean }

Azure SQL および SQL Server の場合、データ API ビルダーでは、SESSION_CONTEXT を利用して、ユーザー指定のメタデータを基になるデータベースに送信できます。 このようなメタデータは、アクセス トークンに存在する要求により、Data API ビルダーで使用できます。 SESSION_CONTEXT データは、その接続が閉じられるまで、データベース接続中にデータベースで使用できます。 詳細については、セッション コンテキスト参照してください。

SQL ストアド プロシージャの例:

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Check if the current user has access to the requested userId
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
        OR SESSION_CONTEXT(N'user_id') = @userId
    BEGIN
        SELECT Id, Name, Age, IsAdmin
        FROM Users
        WHERE Id = @userId;
    END
    ELSE
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END
END;

JSON 構成の例:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')",
    "options": {
      "set-session-context": true
    }
  },
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

説明：

1. ストアド プロシージャ (GetUser):

   • この手順では、呼び出し元がロール SESSION_CONTEXT を持っているか、指定された admin と一致するかどうかを検証するために、userId を確認します。
   • 未承認のアクセスを行うと、エラーが発生します。

2. JSON 構成:

   • アクセス トークンからデータベースにユーザー メタデータを渡すには、set-session-context が有効です。
   • parameters プロパティは、ストアド プロシージャに必要な userId パラメーターをマップします。
   • permissions ブロックにより、認証されたユーザーのみがストアド プロシージャを実行できるようになります。

データ ソース ファイル

データ API ビルダーは、さまざまなデータ ソースに対して複数の構成ファイルをサポートします。1 つは、runtime 設定を管理する最上位ファイルとして指定されています。 すべての構成で同じスキーマが共有されるため、エラーを発生させずに任意のファイルに runtime 設定できます。 子構成は自動的にマージされますが、循環参照は避ける必要があります。 エンティティは、管理を強化するために個別のファイルに分割できますが、エンティティ間のリレーションシップは同じファイル内に存在する必要があります。

形式

{
  "data-source-files": [ <string> ]
}

構成ファイルに関する考慮事項

• すべての構成ファイルに、data-source プロパティを含める必要があります。
• すべての構成ファイルに、entities プロパティを含める必要があります。
• runtime 設定は、他のファイルに含まれている場合でも、最上位の構成ファイルからのみ使用されます。
• 子構成ファイルには、独自の子ファイルを含めることもできます。
• 構成ファイルは、必要に応じてサブフォルダーに整理できます。
• エンティティ名は、すべての構成ファイルで一意である必要があります。
• 異なる構成ファイル内のエンティティ間のリレーションシップはサポートされていません。

例

{
  "data-source-files": [
    "dab-config-2.json"
  ]
}

{
  "data-source-files": [
    "dab-config-2.json", 
    "dab-config-3.json"
  ]
}

サブフォルダーの構文もサポートされています。

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

実行中

runtime セクションでは、公開されているすべてのエンティティの実行時の動作と設定に影響するオプションについて説明します。

形式

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "allow-introspection": <true> (default) | <false>
    },
    "host": {
      "mode": "production" (default) | "development",
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true> | <false> (default),
    "ttl-seconds": <integer; default: 5>
  },
  "pagination": {
    "max-page-size": <integer; default: 100000>,
    "default-page-size": <integer; default: 100>,
    "max-response-size-mb": <integer; default: 158>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": <string>,
      "enabled": <true> | <false> (default)
    }
  }
}

プロパティ

例

複数の一般的な既定のパラメーターが指定されたランタイム セクションの例を次に示します。

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": [
          "*"
        ]
      },
      "authentication": {
        "provider": "StaticWebApps",
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<identity-provider-issuer-uri>"
        }
      }
    },
    "cache": {
      "enabled": true,
      "ttl-seconds": 5
    },
    "pagination": {
      "max-page-size": -1 | <integer; default: 100000>,
      "default-page-size": -1 | <integer; default: 100>,
      "max-response-size-mb": <integer; default: 158>
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (ランタイム)

このオブジェクトは、GraphQL が有効かどうか、およびエンティティを GraphQL 型として公開するために使用される名前を定義します。 このオブジェクトは省略可能であり、既定の名前または設定で十分でない場合にのみ使用されます。 このセクションでは、GraphQL エンドポイントのグローバル設定について説明します。

形式

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "depth-limit": <integer; default: none>,
      "allow-introspection": <true> (default) | <false>,
      "multiple-mutations": <object>
    }
  }
}

プロパティ

有効 (GraphQL ランタイム)

GraphQL エンドポイントをグローバルに有効または無効にするかどうかを定義します。 グローバルに無効にした場合、個々のエンティティ設定に関係なく、GraphQL 要求を介してアクセスできるエンティティはありません。

形式

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
    }
  }
}

例

この例では、GraphQL エンドポイントはすべてのエンティティに対して無効になっています。

{
  "runtime": {
    "graphql": {
      "enabled": false
    }
  }
}

深度制限 (GraphQL ランタイム)

クエリの許容されるクエリの最大深さ。

リレーションシップ定義に基づいて入れ子になったクエリを処理する GraphQL の機能は、ユーザーが複雑で関連するデータを 1 つのクエリでフェッチできるすばらしい機能です。 ただし、ユーザーが入れ子になったクエリを追加し続けるにつれて、クエリの複雑さが増し、最終的にデータベースと API エンドポイントの両方のパフォーマンスと信頼性が損なわれる可能性があります。 このような状況を管理するために、runtime/graphql/depth-limit プロパティは GraphQL クエリの最大許容深度 (および変更) を設定します。 このプロパティを使用すると、開発者はバランスを取ることができ、ユーザーは入れ子になったクエリの利点を享受しながら、システムのパフォーマンスと品質を危険にさらす可能性のあるシナリオを防ぐために制限を設定できます。

例

{
  "runtime": {
    "graphql": {
      "depth-limit": 2
    }
  }
}

パス (GraphQL ランタイム)

GraphQL エンドポイントを使用できるようにする URL パスを定義します。 たとえば、このパラメーターが /graphqlに設定されている場合、GraphQL エンドポイントは /graphqlとして公開されます。 既定では、パスは /graphqlです。

形式

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql)
    }
  }
}

例

この例では、ルート GraphQL URI が /query。

{
  "runtime": {
    "graphql": {
      "path": "/query"
    }
  }
}

イントロスペクションを許可する (GraphQL ランタイム)

このブール型フラグは、GraphQL エンドポイントでスキーマのイントロスペクション クエリを実行する機能を制御します。 イントロスペクションを有効にすると、使用可能なデータの種類、実行できるクエリの種類、使用可能な変更に関する情報をクライアントがスキーマに照会できます。

この機能は、GraphQL API の構造を理解したり、クエリを自動的に生成するツールを開発する際に役立ちます。 ただし、運用環境では、API のスキーマの詳細を隠し、セキュリティを強化することが無効になる場合があります。 既定では、イントロスペクションが有効になっており、GraphQL スキーマを迅速かつ包括的に探索できます。

形式

{
  "runtime": {
    "graphql": {
      "allow-introspection": <true> (default) | <false>
    }
  }
}

例

この例では、イントロスペクションは無効になっています。

{
  "runtime": {
    "graphql": {
      "allow-introspection": false
    }
  }
}

複数の変更 (GraphQL ランタイム)

GraphQL ランタイムのすべての複数の変更操作を構成します。

形式

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

プロパティ

複数の変更 - 作成 (GraphQL ランタイム)

GraphQL ランタイムの複数の作成操作を構成します。

形式

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <true> (default) | <false>
        }
      }
    }
  }
}

プロパティ

例

GraphQL ランタイムで複数の変更を有効にして使用する方法を次に示します。 この場合、create 操作は、runtime.graphql.multiple-mutations.create.enabled プロパティを trueに設定することで、1 つの要求で複数のレコードを作成できるように構成されます。

構成の例

この構成により、複数の create の変更が可能になります。

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["create"]
        }
      ]
    }
  }
}

GraphQL の変更の例

上記の構成を使用すると、次の変更により、1 回の操作で複数の User レコードが作成されます。

mutation {
  createUsers(input: [
    { name: "Alice", age: 30, isAdmin: true },
    { name: "Bob", age: 25, isAdmin: false },
    { name: "Charlie", age: 35, isAdmin: true }
  ]) {
    id
    name
    age
    isAdmin
  }
}

REST (ランタイム)

このセクションでは、REST エンドポイントのグローバル設定について説明します。 これらの設定は、すべてのエンティティの既定値として機能しますが、それぞれの構成でエンティティごとにオーバーライドできます。

形式

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    }
  }
}

プロパティ

有効 (REST ランタイム)

REST エンドポイントのグローバル可用性を決定するブール型フラグ。 無効にした場合、個々のエンティティ設定に関係なく、REST 経由でエンティティにアクセスすることはできません。

形式

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
    }
  }
}

例

この例では、REST API エンドポイントはすべてのエンティティに対して無効になっています。

{
  "runtime": {
    "rest": {
      "enabled": false
    }
  }
}

パス (REST ランタイム)

公開されているすべての REST エンドポイントにアクセスするための URL パスを設定します。 たとえば、path を /api に設定すると、REST エンドポイントは /api/<entity>でアクセスできるようになります。 サブパスは許可されません。 このフィールドは省略可能で、既定値として /api。

形式

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api)
    }
  }
}

例

この例では、ルート REST API URI が /data。

{
  "runtime": {
    "rest": {
      "path": "/data"
    }
  }
}

要求本文 Strict (REST ランタイム)

この設定では、REST の変更操作 (たとえば、POST、PUT、PATCH) の要求本文を厳密に検証する方法を制御します。

• true (既定): テーブル列にマップされない要求本文の追加のフィールドが原因で、BadRequest 例外が発生します。
• false: 追加のフィールドは無視され、有効な列のみが処理されます。

この設定 要求本文は常に無視されるため、GET 要求には適用されません。

特定の列構成での動作

• default() 値を持つ列は、ペイロード内の値が INSERTされている場合にのみ、null 中に無視されます。 ペイロード値に関係なく、UPDATE 中に default() を持つ列は無視されません。
• 計算列は常に無視されます。
• 自動生成された列は常に無視されます。

形式

{
  "runtime": {
    "rest": {
      "request-body-strict": <true> (default) | <false>
    }
  }
}

例

CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY,
    Name NVARCHAR(50) NOT NULL,
    Age INT DEFAULT 18,
    IsAdmin BIT DEFAULT 0,
    IsMinor AS IIF(Age <= 18, 1, 0)
);

構成例

{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}

request-body-strict: false での INSERT 動作

要求ペイロードを します。

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

結果の Insert ステートメントを します。

INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.

応答ペイロードの:

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

update behavior with request-body-strict: false

要求ペイロードを します。

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,     // explicitely set to 'null'
  "IsMinor": true, // ignored because computed
  "ExtraField": "ignored"
}

結果の Update ステートメント :

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

応答ペイロードの:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

ホスト (ランタイム)

ランタイム構成内の host セクションには、Data API ビルダーの運用環境に不可欠な設定が用意されています。 これらの設定には、操作モード、CORS 構成、認証の詳細が含まれます。

形式

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development",
      "max-response-size-mb": <integer; default: 158>,
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

プロパティ

例

開発ホスティング用に構成されたランタイムの例を次に示します。

{
  "runtime": {
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      },
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

モード (ホスト ランタイム)

データ API ビルダー エンジンを development モードで実行するか、production モードで実行するかを定義します。 既定値は production です。

通常、基になるデータベース エラーは、開発中にログの既定の詳細レベルを Debug に設定することで詳細に公開されます。 運用環境では、ログの詳細レベルは Errorに設定されます。

形式

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development"
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

動作

• Swagger は、development モードでのみ使用できます。
• development モードでのみバナナケーキポップが利用可能です。

最大応答サイズ (ランタイム)

特定の結果の最大サイズ (メガバイト単位) を設定します。 この設定により、ユーザーは、基になるデータ ソースからデータをストリーミングするときにホスト プラットフォームのメモリで処理できるデータの量を構成できます。

ユーザーが大規模な結果セットを要求すると、データベースとデータ API ビルダーに負担をかける可能性があります。 これに対処するために、max-response-size-mb を使用すると、開発者は、データ ソースからのデータ ストリームとして、最大応答サイズをメガバイト単位で制限できます。 この制限は、行数ではなく、全体的なデータ サイズに基づいています。 列のサイズはさまざまであるため、一部の列 (テキスト、バイナリ、XML、JSON など) はそれぞれ最大 2 GB を保持できるため、個々の行が非常に大きくなる可能性があります。 この設定は、開発者が応答サイズを制限し、さまざまなデータ型の柔軟性を維持しながらシステムのオーバーロードを防ぐことで、エンドポイントを保護するのに役立ちます。

使用できる値

形式

{
  "runtime": {
    "host": {
      "max-response-size-mb": <integer; default: 158>
    }
  }
}

CORS (ホスト ランタイム)

データ API ビルダー エンジン ホストのクロスオリジン リソース共有 (CORS) 設定。

形式

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      }
    }
  }
}

プロパティ

資格情報を許可する (ホスト ランタイム)

true の場合は、Access-Control-Allow-Credentials CORS ヘッダーを設定します。

形式

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> (default) | <false>
      }
    }
  }
}

配信元 (ホスト ランタイム)

CORS で許可されるオリジンのリストを含む配列を設定します。 この設定では、すべての配信元に対して * ワイルドカードを使用できます。

形式

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"]
      }
    }
  }
}

例

すべての配信元からの資格情報なしで CORS を許可するホストの例を次に示します。

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      }
    }
  }
}

認証 (ホスト ランタイム)

データ API ビルダー ホストの認証を構成します。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

プロパティ

認証と顧客の責任

データ API ビルダーは、より広範なセキュリティ パイプライン内で動作するように設計されており、要求を処理する前に構成する重要な手順があります。 Data API ビルダーは、直接呼び出し元 (Web アプリケーションなど) ではなく、信頼できる ID プロバイダー (Entra ID など) によって提供される有効な JWT トークンに基づいてエンド ユーザーを認証することを理解しておくことが重要です。 要求が Data API ビルダーに到達すると、JWT トークンが有効であると見なされ、特定の要求など、構成済みの前提条件と照合されます。 その後、承認規則が適用され、ユーザーがアクセスまたは変更できる内容が決定されます。

承認に合格すると、データ API ビルダーは接続文字列で指定されたアカウントを使用して要求を実行します。 このアカウントでは、多くの場合、さまざまなユーザー要求を処理するために昇格されたアクセス許可が必要になるため、リスクを軽減するためにアクセス権を最小限に抑えることが不可欠です。 フロントエンド Web アプリケーションと API エンドポイントの間に Private Link を構成し、データ API ビルダーをホストするマシンを強化することで、アーキテクチャをセキュリティで保護することをお勧めします。 これらの対策は、環境のセキュリティを確保し、データを保護し、機密情報へのアクセス、変更、または流出に悪用される可能性のある脆弱性を最小限に抑えるのに役立ちます。

プロバイダー (ホスト ランタイム)

authentication.provider 構成内の host 設定では、データ API ビルダーによって使用される認証方法が定義されます。 リソースへのアクセスを試みるユーザーまたはサービスの ID を API が検証する方法を決定します。 この設定では、さまざまな環境とセキュリティ要件に合わせて調整されたさまざまな認証メカニズムをサポートすることで、デプロイと統合を柔軟に行うことができます。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...
      }
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

JSON Web トークン (ホスト ランタイム)

認証プロバイダーが AzureAD (Microsoft Entra ID) に設定されている場合、このセクションは JSOn Web トークン (JWT) トークンの対象ユーザーと発行者を指定するために必要です。 このデータは、Microsoft Entra テナントに対してトークンを検証するために使用されます。

認証プロバイダーが Microsoft Entra ID に AzureAD 場合に必要です。 このセクションでは、認証の目的の audience テナントに対して受信した JWT トークンを検証するための issuer と AzureAD を指定する必要があります。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

プロパティ

例

データ API ビルダー (DAB) は、Microsoft Entra Identity およびカスタム JSON Web トークン (JWT) サーバーと統合された柔軟な認証サポートを提供します。 この画像では、JWT Server は、サインインが成功したときにクライアントに JWT トークンを発行する認証サービスを表しています。 その後、クライアントはトークンを DAB に渡します。これにより、要求とプロパティを問い合えることができます。

ソリューションで行う可能性のあるさまざまなアーキテクチャの選択を host プロパティの例を次に示します。

Azure Static Web Apps

{
 "host": {
  "mode": "development",
  "cors": {
   "origins": ["https://dev.example.com"],
   "credentials": true
  },
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

StaticWebAppsでは、データ API ビルダーは Azure Static Web Apps が要求を認証することを想定しており、X-MS-CLIENT-PRINCIPAL HTTP ヘッダーが存在します。

Azure App Service

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": false
  },
  "authentication": {
   "provider": "AppService",
   "jwt": {
    "audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
    "issuer": "https://example-appservice-auth.com"
   }
  }
 }
}

認証は、アクセス トークンを発行できるサポートされている ID プロバイダーに委任されます。 取得したアクセス トークンは、Data API ビルダーへの受信要求に含める必要があります。 データ API ビルダーは、提示されたアクセス トークンを検証し、データ API ビルダーがトークンの対象ユーザーであることを確認します。

Microsoft Entra ID

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": true
  },
  "authentication": {
   "provider": "AzureAD",
   "jwt": {
    "audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

シミュレーター (開発専用)

{
 "host": {
  "mode": "development",
  "authentication": {
   "provider": "Simulator"
  }
 }
}

対象ユーザー (ホスト ランタイム)

JWT トークンの対象ユーザー。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<client-id>"
        }
      }
    }
  }
}

発行者 (ホスト ランタイム)

JWT トークンの発行者。

形式

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

改ページ (ランタイム)

REST エンドポイントと GraphQL エンドポイントの改ページ制限を構成します。

形式

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>
    }
  }
}

プロパティ

構成例

{
  "runtime": {
    "pagination": {
      "max-page-size": 1000,
      "default-page-size": 2
    }
  },
  "entities": {
    "Users": {
      "source": "dbo.Users",
      "permissions": [
        {
          "actions": ["read"],
          "role": "anonymous"
        }
      ]
    }
  }
}

REST 改ページ位置の例

この例では、REST GET 要求 https://localhost:5001/api/users を発行すると、value が 2 に設定されているため、default-page-size 配列内の 2 つのレコードが返されます。 さらに多くの結果が存在する場合、Data API ビルダーには応答に nextLink が含まれます。 nextLink には、データの次のページを取得するための $after パラメーターが含まれています。

依頼：

GET https://localhost:5001/api/users

応答：

{
  "value": [
    {
      "Id": 1,
      "Name": "Alice",
      "Age": 30,
      "IsAdmin": true,
      "IsMinor": false
    },
    {
      "Id": 2,
      "Name": "Bob",
      "Age": 17,
      "IsAdmin": false,
      "IsMinor": true
    }
  ],
  "nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}

nextLinkを使用すると、クライアントは次の結果セットをフェッチできます。

GraphQL 改ページ位置の例

GraphQL の場合は、改ページ位置の hasNextPage フィールドと endCursor フィールドを使用します。 これらのフィールドは、より多くの結果が使用可能かどうかを示し、次のページをフェッチするためのカーソルを提供します。

クエリ：

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

応答：

{
  "data": {
    "users": {
      "items": [
        {
          "Id": 1,
          "Name": "Alice",
          "Age": 30,
          "IsAdmin": true,
          "IsMinor": false
        },
        {
          "Id": 2,
          "Name": "Bob",
          "Age": 17,
          "IsAdmin": false,
          "IsMinor": true
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
    }
  }
}

次のページをフェッチするには、次のクエリに endCursor 値を含めます。

カーソルを使用したクエリ:

query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

ページ サイズの調整

REST と GraphQL の両方で、$limit (REST) または first (GraphQL) を使用してクエリごとの結果の数を調整できます。

REST クエリの例:

GET https://localhost:5001/api/users?$limit=5

GraphQL クエリの例:

query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

最大ページ サイズ (改ページ ランタイム)

REST または GraphQL によって返される最上位レコードの最大数を設定します。 ユーザーが max-page-sizeを超える要求を行った場合、結果は max-page-sizeで制限されます。

使用できる値

形式

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>
    }
  }
}

既定のページ サイズ (改ページ ランタイム)

改ページが有効になっているが、明示的なページ サイズが指定されていない場合に返される最上位レコードの既定の数を設定します。

使用できる値

キャッシュ (ランタイム)

ランタイム全体のキャッシュを有効にして構成します。

形式

{
  "runtime": {
    "cache": <object>
  }
}

プロパティ

例

この例では、キャッシュが有効になり、項目は 30 秒後に期限切れになります。

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

有効 (キャッシュ ランタイム)

すべてのエンティティに対してグローバルにキャッシュを有効にします。 既定値は false です。

形式

{
  "runtime": {
    "cache":  {
      "enabled": <boolean>
    }
  }
}

例

この例では、キャッシュは無効になっています。

{
  "runtime": {
    "cache": {
      "enabled": false
    }
  }
}

TTL (秒単位) (キャッシュ ランタイム)

キャッシュされた項目の Time-to-Live (TTL) 値を秒単位で構成します。 この時間が経過すると、項目はキャッシュから自動的に排除されます。 既定値は 5 秒です。

形式

{
  "runtime": {
    "cache":  {
        "ttl-seconds": <integer>
    }
  }
}

例

この例では、キャッシュはグローバルに有効になり、すべての項目は 15 秒後に期限切れになります。

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 15
    }
  }
}

テレメトリ (ランタイム)

このプロパティは、API ログを一元化するように Application Insights を構成します。 その他 について説明します。

形式

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": <true; default: true> | <false>,
        "connection-string": <string>
      }
    }
  }
}

Application Insights (テレメトリ ランタイム)

有効 (Application Insights テレメトリ)

接続文字列 (Application Insights テレメトリ)

エンティティ

entities セクションは、構成ファイルのコアとして機能し、データベース オブジェクトとそれに対応する API エンドポイント間のブリッジを確立します。 このセクションでは、データベース オブジェクトを公開されたエンドポイントにマップします。 このセクションには、プロパティのマッピングとアクセス許可の定義も含まれています。 公開される各エンティティは、専用オブジェクトで定義されます。 オブジェクトのプロパティ名は、公開するエンティティの名前として使用されます。

このセクションでは、プロパティ マッピングやアクセス許可など、データベース内の各エンティティを API で表す方法を定義します。 各エンティティは独自のサブセクション内にカプセル化され、エンティティの名前は構成全体を通じて参照のキーとして機能します。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true; default: true> | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      },
      "graphql": {
        "enabled": <true; default: true> | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": <"query" | "mutation"; default: "query">
      },
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>,
        "parameters": {
          "<parameter-name>": <string | number | boolean>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": <"one" | "many">,
          "target.entity": <string>,
          "source.fields": <array of strings>,
          "target.fields": <array of strings>,
          "linking.object": <string>,
          "linking.source.fields": <array of strings>,
          "linking.target.fields": <array of strings>
        }
      },
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role-name">,
          "actions": <array of strings>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

プロパティ

例

たとえば、この JSON オブジェクトは、User という名前の GraphQL エンティティと、/User パスを介して到達可能な REST エンドポイントを公開するように Data API ビルダーに指示します。 dbo.User データベース テーブルはエンティティをバックアップし、構成により、すべてのユーザーがエンドポイントに匿名でアクセスできるようになります。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

この例では、User エンティティを宣言します。 この名前 User は、エンティティが参照される構成ファイル内の任意の場所で使用されます。 それ以外の場合、エンティティ名はエンドポイントに関連しません。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {} // only when source.type = stored-procedure
      },
      "rest": {
        "enabled": true,
        "path": "/users",
        "methods": [] // only when source.type = stored-procedure
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      },
      "mappings": {
        "id": "Id",
        "name": "Name",
        "age": "Age",
        "isAdmin": "IsAdmin"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],  // "execute" only when source.type = stored-procedure
          "fields": {
            "include": ["id", "name", "age", "isAdmin"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.id"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRole eq 'UserAdmin'"
          }
        }
      ]
    }
  }
}

源

{entity}.source 構成は、API で公開されているエンティティとその基になるデータベース オブジェクトを接続します。 このプロパティは、エンティティが表すデータベース テーブル、ビュー、またはストアド プロシージャを指定し、データの取得と操作のための直接リンクを確立します。

エンティティが 1 つのデータベース テーブルに直接マップされる単純なシナリオでは、ソース プロパティにはそのデータベース オブジェクトの名前のみが必要です。 このシンプルさにより、一般的なユース ケース ("source": "dbo.User") の迅速なセットアップが容易になります。

形式

{
  "entities": {
    "<entity-name>": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">, 
        "key-fields": <array of strings>,
        "parameters": {  // only when source.type = stored-procedure
          "<name>": <string | number | boolean>
        }
      }
    }
  }
}

プロパティ

例

1.単純なテーブル マッピング:

この例では、User エンティティをソース テーブル dbo.Usersに関連付ける方法を示します。

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

構成

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2.ストアド プロシージャの例:

この例では、User エンティティをソース プロシージャ dbo.GetUsersに関連付ける方法を示します。

SQL

CREATE PROCEDURE GetUsers 
     @IsAdmin BIT 
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

構成

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age",
        "IsAdmin": "isAdmin"
      }
    }
  }
}

ストアド プロシージャの場合、mappings プロパティは省略可能です。

オブジェクト

使用するデータベース オブジェクトの名前。 オブジェクトが dbo スキーマに属している場合、スキーマの指定は省略可能です。 さらに、オブジェクト名の角かっこ ([dbo].[Users] と dbo.Usersなど) を使用したり省略したりすることもできます。

例

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

構成

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

スキーマと角かっこを使用しない代替表記法の :

テーブルが dbo スキーマ内にある場合は、スキーマまたは角かっこを省略できます。

{
  "entities": {
    "User": {
      "source": {
        "object": "Users",
        "type": "table"
      }
    }
  }
}

型 (エンティティ)

type プロパティは、エンティティの背後にあるデータベース オブジェクトの種類 (view、table、stored-procedureなど) を識別します。 このプロパティは必須であり、既定値はありません。

形式

{
  "entities": {
    "<entity-name>": {
      "type": <"view" | "stored-procedure" | "table">
    }
  }
}

価値観

例

1.表の例:

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

構成

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2.ビューの例:

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

構成

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age"
      }
    }
  }
}

注: ビューには固有の主キーがないため、key-fields を指定することが重要です。

3.ストアド プロシージャの例:

SQL

CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

構成

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      }
    }
  }
}

キー フィールド

{entity}.key-fields プロパティは、ビューによってサポートされるエンティティに特に必要であるため、Data API Builder は 1 つの項目を識別して返す方法を認識します。 type が viewを指定せずに key-fields に設定されている場合、エンジンは起動を拒否します。 このプロパティはテーブルとストアド プロシージャで使用できますが、そのような場合は使用されません。

形式

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>
      }
    }
  }
}

例: キー フィールドを使用して表示する

この例では、キー フィールドとして dbo.AdminUsers が示されている Id ビューを使用します。

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

構成

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      }
    }
  }
}

パラメーター

parameters 内の entities.{entity}.source プロパティは、ストアド プロシージャによってサポートされるエンティティに使用されます。 これにより、ストアド プロシージャに必要なパラメーター名とデータ型の適切なマッピングが保証されます。

形式

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": "stored-procedure",
        "parameters": {
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>
        }
      }
    }
  }
}

例 1: パラメーターのないストアド プロシージャ

SQL

CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;

構成

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}

例 2: パラメーターを持つストアド プロシージャ

SQL

CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;

構成

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

権限

このセクションでは、関連エンティティにアクセスできるユーザーと、許可されるアクションを定義します。 アクセス許可は、ロールと CRUD 操作 (create、read、update、delete) で定義されます。 permissions セクションでは、関連エンティティにアクセスできるロールと、どのアクションを使用できるかを指定します。

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete", "execute", "*"]
        }
      ]
    }
  }
}

例

例 1: ユーザー エンティティ の匿名ロール

この例では、anonymous ロールは、User エンティティで可能なすべてのアクションへのアクセス権を持って定義されています。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

例 2: 匿名ロール の混合アクション

この例では、User エンティティの文字列とオブジェクト配列のアクションを混在させる方法を示します。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            { "action": "read" },
            "create"
          ]        
        }
      ]
    }
  }
}

匿名ロール: 匿名ユーザーが架空の機密フィールド (secret-fieldなど) を除くすべてのフィールドを読み取ることができます。 "include": ["*"] で "exclude": ["secret-field"] を使用すると、他のすべてのフィールドへのアクセスを許可しながら secret-field が非表示になります。

認証済みロール: 認証済みユーザーが特定のフィールドの読み取りと更新を行うことができます。 たとえば、id、name、age を明示的に含め、isAdmin を除外すると、除外によって包含がオーバーライドされる方法を示すことができます。

管理者ロールの: 管理者は、すべてのフィールドに対してすべての操作 (*) を除外せずに実行できます。 空の "include": ["*"] 配列で "exclude": [] を指定すると、すべてのフィールドへのアクセスが許可されます。

この構成:

"fields": {
  "include": [],
  "exclude": []
}

は実質的に次と同じです。

"fields": {
  "include": ["*"],
  "exclude": []
}

また、次のセットアップも検討してください。

"fields": {
  "include": [],
  "exclude": ["*"]
}

これにより、フィールドが明示的に含まれず、すべてのフィールドが除外され、通常はアクセスが完全に制限されます。

実際の使用: このような構成は、すべてのフィールドへのアクセスを制限するため、直感に反しているように見える場合があります。 ただし、ロールがデータにアクセスせずに特定のアクション (エンティティの作成など) を実行するシナリオで使用できます。

同じ動作ですが、構文は異なります。

"fields": {
  "include": ["Id", "Name"],
  "exclude": ["*"]
}

このセットアップでは、Id フィールドと Name フィールドのみを含めますが、excludeのワイルドカードによりすべてのフィールドが除外されます。

同じロジックを表すもう 1 つの方法は次のとおりです。

"fields": {
  "include": ["Id", "Name"],
  "exclude": ["Id", "Name"]
}

exclude が includeよりも優先されることを考えると、exclude: ["*"] 指定すると、include内のフィールドであっても、すべてのフィールドが除外されることを意味します。 したがって、一見すると、この構成ではフィールドにアクセスできないように見える場合があります。

逆: 目的が Id フィールドと Name フィールドにのみアクセス権を付与する場合は、除外ワイルドカードを使用せずに、include セクションのフィールドのみを指定する方がより明確で信頼性が高くなります。

"fields": {
  "include": ["Id", "Name"],
  "exclude": []
}

プロパティ

役割

定義されたアクセス許可が適用されるロールの名前を含む文字列。 ロールは、要求を実行するアクセス許可コンテキストを設定します。 ランタイム構成で定義されているエンティティごとに、REST および GraphQL エンドポイントを介してエンティティにアクセスする方法を決定する一連のロールと関連するアクセス許可を定義できます。 ロールは追加的ではありません。

Data API Builder は、1 つのロールのコンテキストで要求を評価します。

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          }
        }
      ]
    }
  }
}

例

この例では、reader エンティティに対する read アクセス許可のみを持つ User という名前のロールを定義します。

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

有効なアクセス トークンが 表示され、<custom-role> HTTP ヘッダーが含まれている、アクセス トークンのロール要求にも含まれるユーザー ロールを指定するときに、X-MS-API-ROLE を使用できます。 次に示すのは、User エンティティに対する GET 要求の例で、承認ベアラー トークンと X-MS-API-ROLE ヘッダーの両方を含みます。REST エンドポイント ベース /api では、localhost で異なる言語を使用します。

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");

const response = await fetch('https://localhost:5001/api/User', {
  headers: { 
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});

import requests

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

Actions (string-array)

関連付けられているロールに対して許可される操作の詳細を示す文字列値の配列。 table および view データベース オブジェクトの場合、ロールは、create、read、update、または delete アクションの任意の組み合わせを使用できます。 ストアド プロシージャの場合、ロールは execute アクションのみを持つことができます。

例

この例では、create エンティティの read という名前のロールに対して、contributor という名前のロールに対するアクセス許可と delete アクセス許可を auditor および User します。

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": ["delete"]
        },
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

別の例:

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Actions (object-array)

関連付けられたロールに対して許可される操作を詳細に示すアクション オブジェクトの配列。 table オブジェクトと view オブジェクトの場合、ロールは create、read、update、または deleteの任意の組み合わせを使用できます。 ストアド プロシージャの場合、execute のみが許可されます。

形式

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

プロパティ

例

この例では、フィールドとポリシーの制限を使用して、read エンティティの auditor ロールに User アクセス許可のみを付与します。

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

アクション

データベース オブジェクトで許可される特定の操作を指定します。

価値観

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

例

anonymous ユーザーがストアド プロシージャを execute し、read テーブルから User できる例を次に示します。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "GetUser": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

田畑

データベース オブジェクトに対して特定のフィールドへのアクセスを許可する詳細な仕様。 fields オブジェクトには、includeとexcludeの 2 つのプロパティが含まれており、特定のアクションで許可または制限されるデータベース列を定義します。

形式

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

例

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

構成

この構成により、anonymous ロールは、IsAdminを除くすべてのフィールドをUser エンティティから読み取ることができますが、新しいUser レコードの作成は引き続き許可されます。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["IsAdmin"]
              }
            },
            {
              "action": "create"
            }
          ]
        }
      ]
    }
  }
}

政策

アクションごとに定義された policy セクションは、要求から返される結果を制限するアイテム レベルのセキュリティ規則を設定します。 databaseサブセクションは、クエリの実行中に評価された OData に似た式を示します。この式は、Data API Builder によってクエリ述語に変換されます。

形式

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

基本的な例

次の例では、18 より前のユーザーのみが返されるように、adultReader ロールのread アクションを制限します。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "adultReader",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.Age gt 18"
              }
            }
          ]
        }
      ]
    }
  }
}

データベース

形容

ポリシー内の database プロパティは、クエリの実行中に結果をフィルター処理するために、Data API Builder が SQL 述語に変換する OData に似た式を定義します。 この式は、行が返される true に評価される必要があります。 例えば次が挙げられます。

• @item.Age gt 18 は、 WHERE Users.Age > 18に変換される場合があります。
• @claims.userId eq @item.Id は、要求のユーザー ID が Id フィールドと一致する行に結果を制限します。

指示事項

• @claims: 検証済みのアクセス トークンから要求にアクセスします。
• @item: ポリシーが定義されているエンティティのフィールドを表します。

サポートされている OData に似た演算子

式は、次のような演算子をサポートします。

• 論理: and、 or、 not
• 比較: eq、 gt、 lt
• 単項数値否定: -

たとえば、 "@item.Age gt 18 and @item.Age lt 65" では、19 から 64 歳までのユーザーに結果が制限されます。

エンティティ フィールド名の制限

フィールドは、文字またはアンダースコア (_) で始まり、その後に最大 127 文字、アンダースコア、または数字が続く必要があります。 これらの規則に従っていないフィールドは、ポリシーで直接使用することはできません。 mappings セクションを使用して、ポリシー参照の不適合フィールド名のエイリアスを設定します。

不適合フィールドに mappings を活用する

エンティティ フィールド名が OData の名前付け規則を満たしていない場合は、 mappings セクションでエイリアスを定義します。

{
  "entities": {
    "<entity-name>": {
      "mappings": {
        "<original-field-name>": "<alias>",
        "...": "..."
      }
    }
  }
}

これにより、ポリシーで使用する準拠エイリアスが作成され、エンドポイント間の明確さが向上します。

制限

• ポリシーはテーブルとビューにのみ適用されます。ストアド プロシージャでは使用できません。
• ポリシーは結果をフィルター処理しますが、データベースでのクエリの実行を妨げることはありません。
• アクション ( create、 read、 update、 delete) でのみサポートされます。
• フィールド名は、OData の名前付け規則に従う必要があります。 必要に応じて、エイリアス フィールドへのマッピングを使用します。

例

ポリシーを使用して年齢とユーザー ID に基づいてアクセスを制限するデータ API 構成内で、 User という名前のエンティティについて考えてみましょう。

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

例 1: Age-Based Access

この構成では、 adultReader ロールが制限されるため、 read アクションは Age > 18ユーザーのみを返します。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "adultReader",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.Age gt 18"
              }
            }
          ]
        }
      ]
    }
  }
}

例 2: クレーム ベースのアクセス

この構成では、userId要求が Id フィールドと一致する場合にのみユーザーが自分のレコードを読み取ることができるように、要求を使用してselfReader ロールを制限します。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "selfReader",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.userId eq @item.Id"
              }
            }
          ]
        }
      ]
    }
  }
}

GraphQL (エンティティ)

このオブジェクトは、エンティティの GraphQL 動作を定義します。

形式

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

プロパティ

例

これらの 2 つの例は機能的に同等であり、既定の設定で User エンティティに対して GraphQL を有効にします。

{
  "entities": {
    "User": {
      "graphql": {
        "enabled": true
      }
    }
  }
}

この例では、定義されたエンティティが Userされ、ユーザー データを処理していることを示しています。 GraphQL セグメント内の User エンティティの構成では、GraphQL スキーマでのエンティティの表現方法と対話方法を指定します。

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      }
    }
  }
}

型 (GraphQL エンティティ)

このプロパティは、GraphQL スキーマ内のエンティティの名前付け規則を指定します。 単数形と複数形を指定し、スキーマの読みやすさとユーザー エクスペリエンスをきめ細かく制御します。

形式

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

プロパティ

例

pluralが欠落しているか省略されている場合 (スカラー値など)、Data API Builder は複数形化のために英語の規則を使用して名前を自動的に複数形化しようとします。

明示的な単数形と複数形の名前:

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

GraphQL クエリの例:

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

JSON 応答の例:

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

操作 (GraphQL エンティティ)

ストアド プロシージャにマップされたエンティティの場合、 operation プロパティは、GraphQL 操作が Query または Mutation の型の下に表示されるかどうかを指定します。 この設定は、 機能に影響を与えることなく、スキーマを論理的に整理します。

形式

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

価値観

例

構成

{
  "entities": {
    "UserProcedure": {
      "graphql": {
        "operation": "query" // schema ___location
      },
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

GraphQL スキーマの結果

operationが query に設定されている場合、GraphQL スキーマはプロシージャを Query 型の下に配置します。

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

mutationに設定されている場合は、Mutationの種類の下に表示されます。

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

Enabled (GraphQL エンティティ)

GraphQL エンドポイントを有効または無効にします。 GraphQL エンドポイントを介してエンティティを使用できるかどうかを制御します。 enabled プロパティを切り替えることで、開発者は GraphQL スキーマからエンティティを選択的に公開できます。

形式

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

REST (エンティティ)

構成ファイルの rest セクションは、各データベース エンティティの RESTful エンドポイントの微調整専用です。 このカスタマイズ機能により、公開されている REST API が特定の要件と一致し、ユーティリティと統合機能の両方が向上します。 既定の推定設定と必要なエンドポイント動作の間の潜在的な不一致に対処します。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      }
    }
  }
}

プロパティ

例

これら 2 つの例は機能的に同等です。

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ],
      "rest": true
    }
  }
}

{
  "entities": {
    "Author": {
      ...
      "rest": {
        "enabled": true
      }
    }
  }
}

エンティティの REST 構成のもう 1 つの例を次に示します。

{
  "entities" {
    "User": {
      "rest": {
        "enabled": true,
        "path": "/User"
      },
      ...
    }
  }
}

Enabled (REST エンティティ)

このプロパティは、REST API 内のエンティティの可視性の切り替えとして機能します。 enabled プロパティを true または falseに設定することで、開発者は特定のエンティティへのアクセスを制御し、アプリケーションのセキュリティと機能の要件に合わせて調整された API サーフェスを有効にすることができます。

形式

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

パス (REST エンティティ)

path プロパティは、REST API を介してエンティティにアクセスするために使用される URI セグメントを指定します。 このカスタマイズにより、既定のエンティティ名を超えて、よりわかりやすいエンドポイント パスまたは簡略化されたエンドポイント パスが可能になり、API のナビゲーション性とクライアント側の統合が強化されます。 既定では、パスは /<entity-name>です。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "path": <string; default: "<entity-name>">
      }
    }
  }
}

例

この例では、Author エンドポイントを使用して /auth エンティティを公開します。

{
  "entities": {
    "Author": {
      "rest": {
        "path": "/auth"
      }
    }
  }
}

メソッド (REST エンティティ)

ストアド プロシージャに特に適用できる methods プロパティは、プロシージャが応答できる HTTP 動詞 (GET、POST など) を定義します。 メソッドを使用すると、REST API を介してストアド プロシージャを公開する方法を正確に制御でき、RESTful 標準とクライアントの期待との互換性が確保されます。 このセクションでは、柔軟性と開発者制御に対するプラットフォームのコミットメントを強調し、各アプリケーションの特定のニーズに合わせた正確で直感的な API 設計を可能にします。

省略した場合、または指定されていない場合、methods の既定値は POSTです。

形式

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "methods": ["GET" (default), "POST"]
      }
    }
  }
}

価値観

このプロパティで使用できる値の一覧を次に示します。

例

この例では、stp_get_bestselling_authors ストアド プロシージャが HTTP GET アクションのみをサポートするようにエンジンに指示します。

{
  "entities": {
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": "number"
        }
      },
      "rest": {
        "path": "/best-selling-authors",
        "methods": [ "get" ]
      }
    }
  }
}

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

mappings セクション、データベース オブジェクト フィールドのエイリアスまたは公開された名前を構成できます。 構成された公開名は、GraphQL エンドポイントと REST エンドポイントの両方に適用されます。

形式

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

例

この例では、データベース オブジェクト sku_title の dbo.magazines フィールドは、titleという名前を使用して公開されます。 同様に、sku_status フィールドは、REST エンドポイントと GraphQL エンドポイントの両方で status として公開されます。

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

マッピングの別の例を次に示します。

{
  "entities": {
    "Book": {
      ...
      "mappings": {
        "id": "BookID",
        "title": "BookTitle",
        "author": "AuthorName"
      }
    }
  }
}

Mappings: mappings オブジェクトは、データベース フィールド (BookID、BookTitle、AuthorName) を、外部で使用されるより直感的または標準化された名前 (id、title、author) にリンクします。 このエイリアスは、いくつかの目的で機能します。

• 明確さと整合性の: 基になるデータベース スキーマに関係なく、API 全体で明確で一貫性のある名前付けを使用できます。 たとえば、データベース内の BookID は API の id として表され、開発者がエンドポイントを操作する際に直感的になります。

• GraphQL コンプライアンス: フィールド名をエイリアス化するメカニズムを提供することで、GraphQL インターフェイスを介して公開される名前が GraphQL の名前付け要件に準拠していることを確認します。 名前に注意することは重要です。GraphQL には名前に関する厳密な規則があります (スペースがない、文字やアンダースコアなどで始まる必要があるなど)。 たとえば、データベース フィールド名がこれらの条件を満たしていない場合は、マッピングを使用して準拠している名前にエイリアスを付けることができます。

• 柔軟性: このエイリアスにより、データベース スキーマと API の間に抽象化レイヤーが追加され、もう一方のスキーマに変更を加える必要はありません。 たとえば、データベース内のフィールド名の変更では、マッピングに一貫性がある場合、API ドキュメントまたはクライアント側コードを更新する必要はありません。

• フィールド名難読化: マッピングを使用すると、フィールド名を難読化できます。これにより、権限のないユーザーがデータベース スキーマや格納されているデータの性質に関する機密情報を推測するのを防ぐことができます。

• プロプライエタリな情報の保護: フィールドの名前を変更することで、データベースの元のフィールド名を使用してヒントが表示される可能性がある独自の名前やビジネス ロジックを保護することもできます。

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

このセクションマップには、エンティティが他の公開エンティティとどのように関連しているかをマップするリレーションシップ定義のセットが含まれています。 これらのリレーションシップ定義には、必要に応じて、リレーションシップのサポートと適用に使用される基になるデータベース オブジェクトの詳細を含めることもできます。 このセクションで定義されているオブジェクトは、関連エンティティの GraphQL フィールドとして公開されます。 詳細については、「データ API ビルダーのリレーションシップの内訳を参照してください。

relationships セクションでは、エンティティがデータ API ビルダー内でどのように相互作用するかについて説明し、関連付けと、これらのリレーションシップに対する潜在的なデータベース サポートについて詳しく説明します。 各リレーションシップの relationship-name プロパティは両方とも必須であり、特定のエンティティのすべてのリレーションシップで一意である必要があります。 カスタム名は、明確で識別可能な接続を保証し、これらの構成から生成された GraphQL スキーマの整合性を維持します。

形式

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

プロパティ

例

リレーションシップを検討するときは、一対多の、多対一の、および多対多の リレーションシップ の違いを比較することをお勧めします。

一対多

最初に、公開されている Category エンティティとのリレーションシップの例として、 エンティティと Book リレーションシップを持つ例を考えてみましょう。 ここでは、カーディナリティは manyに設定されています。 各 Category は複数の関連する Book エンティティを持つことができますが、各 Book エンティティは 1 つの Category エンティティにのみ関連付けられます。

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

この例では、source.fields リストはソース エンティティ (id) の Category フィールドを指定します。 このフィールドは、target エンティティ内の関連アイテムに接続するために使用されます。 逆に、target.fields リストでは、ターゲット エンティティ (category_id) の Book フィールドを指定します。 このフィールドは、source エンティティ内の関連アイテムに接続するために使用されます。

このリレーションシップを定義すると、結果として公開される GraphQL スキーマは次の例のようになります。

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

多対一

次に、カーディナリティを に設定する多対一 を することを検討します。 公開された Book エンティティには、1 つの関連 Category エンティティを含めることができます。 Category エンティティには、複数の関連 Book エンティティを含めることができます。

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

ここで、source.fields リストは、ソース エンティティ (category_id) の Book フィールドが、関連するターゲット エンティティ (id) の Category フィールドを参照することを指定します。 逆に、target.fields リストは逆リレーションシップを指定します。 このリレーションシップにより、結果の GraphQL スキーマに書籍からカテゴリへのマッピングが含まれるようになりました。

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

多対多

最後に、多対多 リレーションシップは、many のカーディナリティとより多くのメタデータを使用して定義され、バッキング データベースにリレーションシップを作成するために使用されるデータベース オブジェクトを定義します。 ここでは、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": {
        ...
      }
    }
  }
}

この例では、source.fields と target.fields の両方が、リレーションシップ テーブルでソース (id) エンティティとターゲット (Book) エンティティの両方のプライマリ識別子 (Author) を使用していることを示しています。 linking.object フィールドは、リレーションシップが dbo.books_authors データベース オブジェクトで定義されていることを指定します。 また、linking.source.fields リンク オブジェクトの book_id フィールドが id エンティティの Book フィールドを参照することを指定し、リンク オブジェクトの linking.target.fields フィールドが author_id エンティティの id フィールドを参照することを指定 Author。

この例は、この例のような GraphQL スキーマを使用して説明できます。

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

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

濃度

現在のソース エンティティがターゲット エンティティの 1 つのインスタンスにのみ関連付けられているか、複数に関連付けられているのか指定します。

価値観

このプロパティで使用できる値の一覧を次に示します。

ターゲット エンティティ

リレーションシップのターゲットである構成内の他の場所で定義されているエンティティの名前。

ソース フィールド

ターゲット エンティティ内の関連アイテムへの接続に使用する ソース エンティティのマッピングに使用するフィールドを定義する省略可能なパラメーター。

ターゲット フィールド

ソース エンティティ内の関連アイテムへの接続に使用される、ターゲット エンティティのマッピングに使用するフィールドを定義する省略可能なパラメーター。

オブジェクトまたはエンティティのリンク

多対多リレーションシップの場合、他の 2 つのエンティティ間のリレーションシップを定義するために必要なデータを含むデータベース オブジェクトまたはエンティティの名前。

ソース フィールドのリンク

ソース エンティティに関連するデータベース オブジェクトまたはエンティティ フィールドの名前。

リンク先フィールド

ターゲット エンティティに関連するデータベース オブジェクトまたはエンティティ フィールドの名前。

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

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

形式

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

プロパティ

例

この例では、キャッシュが有効になり、項目は 30 秒後に期限切れになります。

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

有効 (キャッシュ エンティティ)

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

データベース オブジェクトのサポート

HTTP ヘッダーのサポート

形式

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <boolean> (default: false)
      }
    }
  }
}

例

この例では、キャッシュは無効になっています。

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": false
      }
    }
  }
}

TTL (秒単位) (キャッシュ エンティティ)

キャッシュされた項目の Time-to-Live (TTL) 値を秒単位で構成します。 この時間が経過すると、項目はキャッシュから自動的に排除されます。 既定値は 5 秒です。

形式

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "ttl-seconds": <integer; inherited>
      }
    }
  }
}

例

この例では、キャッシュが有効になり、項目は 15 秒後に期限切れになります。 省略すると、この設定はグローバル設定または既定値を継承します。

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

関連コンテンツ

• Functions リファレンス
• コマンドライン インターフェイス (CLI) リファレンス