Справочник по схеме конфигурации построителя данных

Для обработчика API данных требуется файл конфигурации. Файл конфигурации построителя данных данных предоставляет структурированный и комплексный подход к настройке API, подробное описание всех переменных среды до конфигураций, относящихся к сущностям. Этот документ в формате JSON начинается со свойства $schema. Эта настройка проверяет документ.

Свойства database-type и connection-string обеспечить простую интеграцию с системами баз данных, от базы данных SQL Azure до API NoSQL Cosmos DB.

Файл конфигурации может включать такие параметры, как:

• Сведения о службе базы данных и подключении
• Глобальные параметры конфигурации и конфигурации среды выполнения
• Набор предоставляемых сущностей
• Метод проверки подлинности
• Правила безопасности, необходимые для доступа к удостоверениям
• Правила сопоставления имен между API и базой данных
• Связи между сущностями, которые не могут быть выведены
• Уникальные функции для конкретных служб баз данных

Общие сведения о синтаксисе

Ниже приведена быстрая разбивка основных разделов в файле конфигурации.

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

Свойства верхнего уровня

Ниже приведено описание свойств верхнего уровня в формате таблицы:

Свойство	Описание
$schema	Указывает схему JSON для проверки, обеспечивая соответствие конфигурации требуемому формату.
источника данных	Содержит сведения о типе базы данных и строке подключения, необходимой для установления подключения к базе данных.
файлов источника данных	Необязательный массив, указывающий другие файлы конфигурации, которые могут определять другие источники данных.
среды выполнения	Настраивает поведение среды выполнения и параметры, в том числе вложенные свойства для REST, GraphQL, узла, кэшаи телеметрии.
сущностей	Определяет набор сущностей (таблиц базы данных, представлений и т. д.), предоставляемых через API, включая их сопоставления , разрешенияи связи.

Примеры конфигураций

Ниже приведен пример файла конфигурации, который содержит только необходимые свойства для одной простой сущности. Этот пример предназначен для иллюстрации минимального сценария.

{
  "$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": ["*"]
        }
      ]
    }
  }
}

Пример более сложного сценария см. в сквозной конфигурации.

Средах

Файл конфигурации построителя данных может поддерживать сценарии, в которых необходимо поддерживать несколько сред, аналогичных файлу appSettings.json в ASP.NET Core. Платформа предоставляет три общих значений среды; Development, Stagingи Production; но вы можете использовать любое выбранное значение среды. Среда, используемая конструктором API данных, должна быть настроена с помощью переменной среды DAB_ENVIRONMENT.

Рассмотрим пример, в котором требуется базовая конфигурация и конфигурация для разработки. В этом примере требуется два файла конфигурации:

	Окружающая среда
dab-config.json	Основа
dab-config.Development.json	Развитие

Чтобы использовать конфигурацию для разработки, необходимо задать для переменной среды DAB_ENVIRONMENT значение Development.

Файлы конфигурации для конкретной среды переопределяют значения свойств в базовом файле конфигурации. В этом примере, если значение connection-string задано в обоих файлах, используется значение из файла *.Development.json.

См. эту матрицу, чтобы лучше понять, какое значение используется в зависимости от того, где указанное значение (или не указано) в любом файле.

	, указанные в базовой конфигурации	Не указано в базовой конфигурации
, указанные в текущей конфигурации среды	Текущая среда	Текущая среда
Не указано в текущей конфигурации среды	Основа	Никакой

Пример использования нескольких файлов конфигурации см. в использовании построителя API данных с средами.

Свойства конфигурации

В этом разделе содержатся все возможные свойства конфигурации, доступные для файла конфигурации.

Схема

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
$root	$schema	струна	✔️ Да	Никакой

Каждый файл конфигурации начинается со свойства $schema, указывая схему JSON для проверки.

Формат

{
  "$schema": <string>
}

Примеры

Файлы схемы доступны для версий, 0.3.7-alpha на определенных URL-адресах, обеспечивая использование правильной версии или последней доступной схемы.

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.

Ниже приведены несколько примеров допустимых значений схемы.

Версия	УРИ	Описание
0.3.7-альфа	https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json	Использует схему конфигурации из альфа-версии средства.
0.10.23	https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json	Использует схему конфигурации для стабильного выпуска средства.
Самый поздний	https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json	Использует последнюю версию схемы конфигурации.

Заметка

Версии построителя API данных до 0.3.7-альфа- могут иметь другой универсальный код ресурса (URI) схемы.

Источник данных

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
$root	data-source	струна	✔️ Да	Никакой

В разделе 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>
    }
  }
}

Свойства

	Обязательно	Тип
database-type	✔️ Да	строка перечисления
connection-string	✔️ Да	струна
options	❌ Нет	объект

Тип базы данных

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
data-source	database-type	перечисление строки	✔️ Да	Никакой

Строка перечисления, используемая для указания типа базы данных, используемой в качестве источника данных.

Формат

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

Значения типов

Свойство type указывает тип серверной базы данных.

Тип	Описание	Минимальная версия
mssql	База данных SQL Azure	-
mssql	Azure SQL MI	-
mssql	SQL Server	2016
dwsql	Azure Synapse Analytics	-
dwsql	Склад тканей	-
dwsql	Конечная точка Аналитики SQL Fabric	-
postgresql	PostgreSQL	Версии. 11
mysql	MySQL	Версии. 8
cosmosdb_nosql	Azure Cosmos DB для NoSQL	-
cosmosdb_postgresql	Azure Cosmos DB для PostgreSQL	-

Строка подключения

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
data-source	connection-string	струна	✔️ Да	Никакой

Значение строки , содержащей допустимую строку подключения для подключения к целевой службе базы данных. Строка подключения ADO.NET для подключения к серверной базе данных. Дополнительные сведения см. встрок подключения ADO.NET.

Формат

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

Устойчивость подключения

Построитель данных автоматически повторяет запросы базы данных после обнаружения временных ошибок. Логика повторных попыток следует стратегии экспоненциальной, где максимальное количество повторных попыток пять. Длительность обратного выполнения повторных попыток после последующих запросов вычисляется с помощью этой формулы (если текущая попытка повтора r): $r^2$

С помощью этой формулы можно вычислить время каждой попытки повтора в секундах.

Попыток	Первый	Второй	Третья	Четвертая	Пятый
Товары второго сорта	2s	4s	8s	16s	32s

SQL Azure и SQL Server

Построитель данных использует библиотеку SqlClient для подключения к SQL Azure или SQL Server с помощью строки подключения, предоставленной в файле конфигурации. Список всех поддерживаемых параметров строки подключения доступен здесь: SqlConnection.ConnectionString Property.

Построитель данных также может подключаться к целевой базе данных с помощью управляемых удостоверений служб (MSI) при размещении построителя данных в Azure. DefaultAzureCredential, определенный в библиотеке Azure.Identity, используется для подключения с помощью известных удостоверений, если не указать имя пользователя или пароль в строке подключения. Дополнительные сведения см. в DefaultAzureCredential примерах.

• управляемого удостоверения, назначаемого пользователем (UMI): добавьте проверки подлинности и свойства идентификатора пользователя в строку подключения при замене идентификатора клиента назначаемого пользователем управляемого удостоверения: .
• управляемое удостоверение, назначаемое системой (SMI): добавьте свойство аутентификации и исключите UserId и пароль из строки подключения: Authentication=Active Directory Managed Identity;. Отсутствие UserId и свойства строки подключения пароля сигнализирует DAB для проверки подлинности с помощью назначенного системой управляемого удостоверения.

Дополнительные сведения о настройке управляемого удостоверения службы с помощью SQL Azure или SQL Server см. в управляемых удостоверений в Microsoft Entra для SQL Azure.

Примеры

Значение, используемое для строки подключения, в значительной степени зависит от службы базы данных, используемой в вашем сценарии. Вы всегда можете сохранить строку подключения в переменной среды и получить к ней доступ с помощью функции @env().

	Ценность	Описание
использовать строковое значение базы данных SQL Azure	Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;	Строка подключения к учетной записи базы данных SQL Azure. Дополнительные сведения см. в строках подключения базы данных SQL Azure.
использовать строковое значение базы данных Azure для PostgreSQL	Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;	Строка подключения к учетной записи Базы данных Azure для PostgreSQL. Дополнительные сведения см. в строках подключения базы данных Azure для PostgreSQL.
использовать строковое значение Azure Cosmos DB для NoSQL	AccountEndpoint=<endpoint>;AccountKey=<key>;	Строка подключения к учетной записи Azure Cosmos DB для NoSQL. Дополнительные сведения см. в строках подключения Azure Cosmos DB для NoSQL.
использовать строковое значение базы данных Azure для MySQL	Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;	Строка подключения к учетной записи Базы данных Azure для MySQL. Дополнительные сведения см. в строках подключения базы данных Azure для MySQL.
переменная среды Access	@env('SQL_CONNECTION_STRING')	Доступ к переменной среды с локального компьютера. В этом примере ссылается переменная среды SQL_CONNECTION_STRING.

Кончик

Рекомендуется не хранить конфиденциальную информацию в файле конфигурации. По возможности используйте @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')"
}

Заметка

Указанные параметры, такие как database, containerи schema зависят от API NoSQL Azure Cosmos DB, а не API PostgreSQL. Для Azure Cosmos DB с помощью API PostgreSQL параметры не будут включать database, containerили schema, как в настройке NoSQL.

Параметры

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
data-source	options	объект	❌ Нет	Никакой

Необязательный раздел дополнительных параметров значения ключа для определенных подключений к базе данных.

Является ли раздел options обязательным или не зависит от используемой службы базы данных.

Формат

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

параметры: { set-session-context: boolean }

Для SQL Azure и SQL Server построитель данных может воспользоваться преимуществами SESSION_CONTEXT отправки метаданных, указанных пользователем, в базовую базу данных. Такие метаданные доступны построителю 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 гарантирует, что только прошедшие проверку подлинности пользователи могут выполнять хранимую процедуру.

Файлы источника данных

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
$root	data-source-files	массив строк	❌ Нет	Никакой

Построитель данных поддерживает несколько файлов конфигурации для разных источников данных, а один — в качестве файла верхнего уровня, который управляет 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"
  ]
}

Среды выполнения

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
$root	runtime	объект	✔️ Да	Никакой

В разделе 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)
    }
  }
}

Свойства

	Обязательно	Тип
rest	❌ Нет	объект
graphql	❌ Нет	объект
host	❌ Нет	объект
cache	❌ Нет	объект

Примеры

Ниже приведен пример раздела среды выполнения с несколькими общими параметрами по умолчанию.

{
  "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 (среда выполнения)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime	graphql	объект	❌ Нет	Никакой

Этот объект определяет, включен ли GraphQL и имя[s], используемое для предоставления сущности в виде типа 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>
    }
  }
}

Свойства

Свойство	Обязательно	Тип	По умолчанию
enabled	❌ Нет	булев	Истинный
path	❌ Нет	струна	/graphql (по умолчанию)
allow-introspection	❌ Нет	булев	Истинный
multiple-mutations	❌ Нет	объект	{ create: { enabled: false } }

Включено (среда выполнения GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.graphql	enabled	булев	❌ Нет	Никакой

Определяет, следует ли включать или отключать конечные точки GraphQL глобально. Если они отключены глобально, сущности не будут доступны через запросы GraphQL независимо от параметров отдельных сущностей.

Формат

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

Примеры

В этом примере конечная точка GraphQL отключена для всех сущностей.

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

Ограничение глубины (среда выполнения GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.graphql	depth-limit	целое число	❌ Нет	Никакой

Максимальная допустимая глубина запроса.

Возможность GraphQL обрабатывать вложенные запросы на основе определений связей является невероятной функцией, что позволяет пользователям получать сложные связанные данные в одном запросе. Однако по мере того как пользователи продолжают добавлять вложенные запросы, сложность запроса увеличивается, что в конечном итоге может скомпрометировать производительность и надежность базы данных и конечной точки API. Для управления этой ситуацией свойство runtime/graphql/depth-limit задает максимальную глубину запроса GraphQL (и мутации). Это свойство позволяет разработчикам балансировать, позволяя пользователям наслаждаться преимуществами вложенных запросов при размещении ограничений, чтобы предотвратить сценарии, которые могут поставить под угрозу производительность и качество системы.

Примеры

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

Путь (среда выполнения GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.graphql	path	струна	❌ Нет	"/graphql"

Определяет путь URL-адреса, по которому предоставляется конечная точка GraphQL. Например, если для этого параметра задано значение /graphql, конечная точка GraphQL предоставляется как /graphql. По умолчанию путь имеет значение /graphql.

Важный

Вложенные пути не допускаются для этого свойства. Настраиваемое значение пути для конечной точки GraphQL в настоящее время недоступно.

Формат

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

Примеры

В этом примере корневой URI GraphQL является /query.

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

Разрешить интроспекцию (среда выполнения GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.graphql	allow-introspection	булев	❌ Нет	Истинный

Этот логический флаг управляет возможностью выполнения запросов инкроспекции схемы в конечной точке GraphQL. Включение интроспекции позволяет клиентам запрашивать схему для получения сведений о типах доступных данных, типах запросов, которые они могут выполнять, и доступных изменениях.

Эта функция полезна во время разработки для понимания структуры API GraphQL и средств, которые автоматически создают запросы. Однако в рабочих средах может быть отключено, чтобы скрыть сведения о схеме API и повысить безопасность. По умолчанию включена истроспекция, позволяющая немедленно и комплексно искать схему GraphQL.

Формат

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

Примеры

В этом примере интроспекция отключена.

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

Несколько мутаций (среда выполнения GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.graphql	multiple-mutations	объект	❌ Нет	Никакой

Настраивает все несколько операций изменения для среды выполнения GraphQL.

Заметка

По умолчанию несколько мутаций не включены и должны быть явно настроены для включения.

Формат

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

Свойства

	Обязательно	Тип
create	❌ Нет	объект

Несколько мутаций— создание (среда выполнения GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.graphql.multiple-mutations	create	булев	❌ Нет	Ложный

Настраивает несколько операций создания для среды выполнения GraphQL.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
enabled	✔️ Да	булев	Истинный

Примеры

Ниже показано, как включить и использовать несколько мутаций в среде выполнения GraphQL. В этом случае операция create настроена, чтобы разрешить создание нескольких записей в одном запросе, задав для свойства runtime.graphql.multiple-mutations.create.enabled значение true.

Пример конфигурации

Эта конфигурация включает несколько create мутаций:

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

Пример мутации GraphQL

Используя приведенную выше конфигурацию, следующая мутация создает несколько 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 (среда выполнения)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime	rest	объект	❌ Нет	Никакой

В этом разделе описаны глобальные параметры конечных точек REST. Эти параметры служат по умолчанию для всех сущностей, но их можно переопределить на основе каждой сущности в соответствующих конфигурациях.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
enabled	❌ Нет	булев	Истинный
path	❌ Нет	струна	/api
request-body-strict	❌ Нет	булев	Истинный

Включено (среда выполнения REST)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.rest	enabled	булев	❌ Нет	Никакой

Логический флаг, определяющий глобальную доступность конечных точек REST. При отключении сущности не могут быть доступны через REST независимо от параметров отдельных сущностей.

Формат

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

Примеры

В этом примере конечная точка REST API отключена для всех сущностей.

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

Путь (среда выполнения REST)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.rest	path	струна	❌ Нет	"/api"

Задает путь URL-адреса для доступа ко всем предоставляемым конечным точкам REST. Например, установка path для /api делает конечную точку REST доступной по /api/<entity>. Подпаты не разрешены. Это поле является необязательным, /api в качестве значения по умолчанию.

Заметка

При развертывании построителя API данных с помощью статических веб-приложений (предварительная версия) служба Azure автоматически внедряет дополнительные подпаты /data-api в URL-адрес. Это поведение обеспечивает совместимость с существующими функциями статического веб-приложения. Результирующая конечная точка будет /data-api/api/<entity>. Это относится только к статическим веб-приложениям.

Формат

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

Важный

Предоставленные пользователем вложенные пути не допускаются для этого свойства.

Примеры

В этом примере корневой URI REST API /data.

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

Кончик

Если определить сущность Author, конечная точка для этой сущности будет /data/Author.

Строгое тело запроса (среда выполнения REST)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.rest	request-body-strict	булев	❌ Нет	Истинный

Этот параметр определяет, как строго проверяется текст запроса для операций мутации REST (например, POST, PUT, PATCH) .

• true (по умолчанию): дополнительные поля в тексте запроса, не сопоставленные с столбцами таблицы, вызывают исключение BadRequest.
• false. Дополнительные поля игнорируются и обрабатываются только допустимые столбцы.

Этот параметр не применяется к запросам GET, так как текст запроса всегда игнорируется.

Поведение с определенными конфигурациями столбцов

• Столбцы со значением по умолчанию () игнорируются во время INSERT только в том случае, если их значение в полезных данных null. Столбцы со значением по умолчанию () не игнорируются во время UPDATE независимо от значения полезных данных.
• Вычисляемые столбцы всегда игнорируются.
• Автоматически созданные столбцы всегда игнорируются.

Формат

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

Поведение INSERT с request-body-strict: false

полезных данных запроса:

{
  "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 с помощью request-body-strict: false

полезных данных запроса:

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

результирующий оператор обновления:

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`)
}

Узел (среда выполнения)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime	host	объект	❌ Нет	Никакой

Раздел host в конфигурации среды выполнения предоставляет параметры, важные для операционной среды построителя данных. К этим параметрам относятся рабочие режимы, конфигурация 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>"
        }
      }
    }
  }
}

Свойства

Свойство	Обязательно	Тип	По умолчанию
mode	❌ Нет	строка перечисления	производство
cors	❌ Нет	объект	Никакой
authentication	❌ Нет	объект	Никакой

Примеры

Ниже приведен пример среды выполнения, настроенной для размещения разработки.

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

Режим (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host	mode	струна	❌ Нет	"production"

Определяет, должен ли модуль построителя данных работать в development или production режиме. Значение по умолчанию — production.

Как правило, базовые ошибки базы данных предоставляются подробно, задав уровень детализации по умолчанию для журналов Debug при запуске в разработке. В рабочей среде для журналов задан уровень детализации Error.

Кончик

Уровень журнала по умолчанию можно переопределить с помощью dab start --LogLevel <level-of-detail>. Дополнительные сведения см. в справочнике по интерфейсу командной строки (CLI).

Формат

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

Значения

Ниже приведен список разрешенных значений для этого свойства:

	Описание
production	Использование при размещении в рабочей среде в Azure
development	Использование в разработке на локальном компьютере

Поведения

• Доступно только в development режиме Swagger.
• Только в режиме development доступен банановый торт Pop.

Максимальный размер ответа (среда выполнения)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host	max-response-size-mb	целое число	❌ Нет	158

Задает максимальный размер (в мегабайтах) для любого заданного результата. Этот параметр позволяет пользователям настраивать объем данных, которые может обрабатывать память платформы узла при потоковой передаче данных из базовых источников данных.

Когда пользователи запрашивают большие результирующие наборы, это может напрягать построитель баз данных и API данных. Чтобы устранить эту проблему, max-response-size-mb позволяет разработчикам ограничить максимальный размер ответа, измеряемый в мегабайтах, как потоки данных из источника данных. Это ограничение зависит от общего размера данных, а не количества строк. Так как столбцы могут отличаться по размеру, некоторые столбцы (например, текст, двоичный, XML или JSON) могут содержать до 2 ГБ каждый, что делает отдельные строки потенциально очень большими. Этот параметр помогает разработчикам защитить конечные точки, заключив размеры откликов и предотвращая перегрузки системы при сохранении гибкости для разных типов данных.

Допустимые значения

Ценность	Результат
null	По умолчанию значение 158 мегабайт, если не задано или явно задано значение null.
integer	Поддерживается любое 32-разрядное целое число.
< 0	Не поддерживается. Ошибки проверки возникают, если задано значение менее 1 МБ.

Формат

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

CORS (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host	cors	объект	❌ Нет	Никакой

Параметры общего доступа к ресурсам между источниками (CORS) для узла ядра построителя данных.

Формат

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

Свойства

	Обязательно	Тип
allow-credentials	❌ Нет	булев
origins	❌ Нет	массив строк

Разрешить учетные данные (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host.cors	allow-credentials	булев	❌ Нет	Ложный

Если значение true, задает заголовок CORS Access-Control-Allow-Credentials.

Заметка

Дополнительные сведения о заголовке CORS см. в справочнике Access-Control-Allow-Credentialsпо CORS веб-документации MDN.

Формат

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

Источники (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host.cors	origins	массив строк	❌ Нет	Никакой

Задает массив со списком разрешенных источников для CORS. Этот параметр позволяет * подстановочный знак для всех источников.

Формат

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

Примеры

Ниже приведен пример узла, который позволяет CORS без учетных данных из всех источников.

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

Проверка подлинности (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host	authentication	объект	❌ Нет	Никакой

Настраивает проверку подлинности для узла построителя данных.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
provider	❌ Нет	строка перечисления	StaticWebApps
jwt	❌ Нет	объект	Никакой

аутентификации и обязанности клиента

Построитель API данных предназначен для работы в более широком конвейере безопасности, и перед обработкой запросов необходимо выполнить важные действия. Важно понимать, что построитель API данных не выполняет проверку подлинности прямого вызывающего объекта (например, веб-приложения), а конечный пользователь, основанный на допустимом токене JWT, предоставленном доверенным поставщиком удостоверений (например, идентификатором Записи). Когда запрос достигает построителя API данных, предполагается, что маркер JWT действителен и проверяет его на наличие необходимых компонентов, таких как определенные утверждения. Затем применяются правила авторизации, чтобы определить, к чему пользователь может получить доступ или изменить.

После передачи авторизации построитель данных выполняет запрос с помощью учетной записи, указанной в строке подключения. Так как эта учетная запись часто требует повышенных разрешений для обработки различных запросов пользователей, важно свести к минимуму права доступа для снижения риска. Рекомендуется защитить архитектуру, настроив приватный канал между интерфейсным веб-приложением и конечной точкой API, а также заверяя машинный построитель API данных. Эти меры помогают обеспечить безопасность вашей среды, защиту данных и минимизацию уязвимостей, которые могут быть использованы для доступа, изменения или эксфильтрации конфиденциальной информации.

Поставщик (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host.authentication	provider	струна	❌ Нет	"StaticWebApps"

Параметр authentication.provider в конфигурации host определяет метод проверки подлинности, используемый построителем API данных. Он определяет, как API проверяет удостоверение пользователей или служб, пытающихся получить доступ к своим ресурсам. Этот параметр обеспечивает гибкость в развертывании и интеграции, поддерживая различные механизмы проверки подлинности, адаптированные к различным средам и требованиям безопасности.

Поставщик	Описание
StaticWebApps	Указывает построителю API данных искать набор заголовков HTTP, присутствующих только при выполнении в среде статических веб-приложений.
AppService	Если среда выполнения размещена в Службе приложений Azure с включенной проверкой подлинности AppService и настроена (EasyAuth).
AzureAd	Удостоверение Microsoft Entra необходимо настроить таким образом, чтобы оно удостоверялось для проверки подлинности запроса, отправленного в построитель API данных (приложение сервера). Дополнительные сведения см. в проверки подлинности Идентификатора Microsoft Entra.
Simulator	Настраиваемый поставщик проверки подлинности, который предписывает обработчику построителя данных обрабатывать все запросы как прошедшие проверку подлинности. Дополнительные сведения см. в локальной проверки подлинности.

Формат

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

Значения

Ниже приведен список разрешенных значений для этого свойства:

	Описание
StaticWebApps	Статические веб-приложения Azure
AppService	Служба приложений Azure
AzureAD	Идентификатор Microsoft Entra
Simulator	Тренажёр

Веб-маркеры JSON (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host.authentication	jwt	объект	❌ Нет	Никакой

Если для поставщика проверки подлинности задано значение AzureAD (идентификатор Microsoft Entra ID), этот раздел требуется для указания аудитории и издателей маркера JSOn Web Token (JWT). Эти данные используются для проверки маркеров в клиенте Microsoft Entra.

Требуется, если поставщик проверки подлинности AzureAD для идентификатора Microsoft Entra. В этом разделе необходимо указать audience и issuer для проверки полученного токена JWT в соответствии с предполагаемым клиентом AzureAD для проверки подлинности.

Оправа	Описание
публика	Определяет целевого получателя маркера; обычно идентификатор приложения, зарегистрированный в Microsoft Entra Identity (или поставщик удостоверений), гарантируя, что маркер действительно выдан для вашего приложения.
эмитент	Указывает URL-адрес центра выдачи, который является службой маркеров, которая выпустила JWT. Этот URL-адрес должен соответствовать URL-адресу издателя поставщика удостоверений, из которого был получен JWT, проверяя источник маркера.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
audience	❌ Нет	струна	Никакой
issuer	❌ Нет	струна	Никакой

Примеры

Построитель данных (DAB) предоставляет гибкую поддержку проверки подлинности, интегрируя с Microsoft Entra Identity и пользовательскими серверами веб-маркера JSON (JWT). На этом изображении сервер JWT представляет службу проверки подлинности, которая выдает маркеры JWT клиентам при успешном входе. Затем клиент передает маркер в DAB, который может просить свои утверждения и свойства.

Ниже приведены примеры свойства host с учетом различных вариантов архитектуры, которые можно сделать в решении.

Статические веб-приложения Azure

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

При использовании StaticWebAppsпостроитель API данных ожидает, что статические веб-приложения Azure проходят проверку подлинности запроса, а заголовок HTTP X-MS-CLIENT-PRINCIPAL присутствует.

Служба приложений Azure

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

Проверка подлинности делегирована поддерживаемой поставщику удостоверений, где можно вывести маркер доступа. Полученный маркер доступа должен быть включен в входящие запросы к построителю API данных. Затем построитель API данных проверяет все представленные маркеры доступа, гарантируя, что построитель API данных был целевой аудиторией маркера.

Идентификатор Microsoft Entra

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

Аудитория (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host.authentication.jwt	audience	струна	❌ Нет	Никакой

Аудитория для токена JWT.

Формат

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

Издатель (среда выполнения узла)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.host.authentication.jwt	issuer	струна	❌ Нет	Никакой

Издатель маркера JWT.

Формат

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

Разбиение на страницы (среда выполнения)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime	pagination	объект	❌ Нет	Никакой

Настраивает ограничения разбиения на страницы для конечных точек REST и GraphQL.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
max-page-size	❌ Нет	целое число	100,000
default-page-size	❌ Нет	целое число	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, так как default-page-size имеет значение 2. Если существуют дополнительные результаты, построитель 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).

значение $limit/first	Поведение
-1	По умолчанию — max-page-size.
< max-page-size	Ограничивает результаты указанным значением.
0 или < -1	Не поддерживается.
> max-page-size	Ограничен max-page-size.

Пример ЗАПРОСА REST:

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

Пример запроса GraphQL:

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

Максимальный размер страницы (среда выполнения разбиения на страницы)

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.pagination	max-page-size	int	❌ Нет	100,000

Задает максимальное количество записей верхнего уровня, возвращаемых REST или GraphQL. Если пользователь запрашивает более max-page-size, результаты будут ограничены max-page-size.

Допустимые значения

Ценность	Результат
-1	По умолчанию используется максимальное поддерживаемое значение.
integer	Поддерживается любое 32-разрядное целое число.
< -1	Не поддерживается.
0	Не поддерживается.

Формат

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

---

Размер страницы по умолчанию (среда выполнения разбиения на страницы)

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.pagination	default-page-size	int	❌ Нет	100

Задает число записей верхнего уровня по умолчанию, возвращаемых при включении разбиения на страницы, но не указан явный размер страницы.

Допустимые значения

Ценность	Результат
-1	По умолчанию используется текущий параметр max-page-size.
integer	Любое положительное целое число меньше текущего max-page-size.
< -1	Не поддерживается.
0	Не поддерживается.

Кэш (среда выполнения)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime	cache	объект	❌ Нет	Никакой

Включает и настраивает кэширование для всей среды выполнения.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
enabled	❌ Нет	булев	Никакой
ttl-seconds	❌ Нет	целое число	5

Примеры

В этом примере кэш включен и элементы истекают через 30 секунд.

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

Включено (среда выполнения кэша)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.cache	enabled	булев	❌ Нет	Ложный

Включает кэширование глобально для всех сущностей. По умолчанию — false.

Формат

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

Примеры

В этом примере кэш отключен.

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

TTL в секундах (среда выполнения кэша)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.cache	ttl-seconds	целое число	❌ Нет	5

Настраивает значение времени в реальном времени (TTL) в секундах для кэшированных элементов. По истечении этого времени элементы автоматически удаляются из кэша. Значение по умолчанию — 5 секунд.

Формат

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

Примеры

В этом примере кэш включен глобально и все элементы истекают через 15 секунд.

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

Телеметрия (среда выполнения)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime	telemetry	объект	❌ Нет	Никакой

Это свойство настраивает Application Insights для централизации журналов API. Дополнительные сведения см. здесь.

Формат

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

Application Insights (среда выполнения телеметрии)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.telemetry	application-insights	объект	✔️ Да	Никакой

Включено (телеметрия Application Insights)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.telemetry.application-insights	enabled	булев	❌ Нет	Истинный

Строка подключения (телеметрия Application Insights)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
runtime.telemetry.application-insights	connection-string	струна	✔️ Да	Никакой

Объекты

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
$root	entities	объект	✔️ Да	Никакой

Раздел 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>
          }
        }
      ]
    }
  }
}

Свойства

	Обязательно	Тип
source	✔️ Да	объект
permissions	✔️ Да	массив
rest	❌ Нет	объект
graphql	❌ Нет	объект
mappings	❌ Нет	объект
relationships	❌ Нет	объект
cache	❌ Нет	объект

Примеры

Например, этот объект JSON указывает построителю данных предоставить сущность GraphQL с именем User и доступную конечную точку REST с помощью пути /User. Таблица базы данных 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'"
          }
        }
      ]
    }
  }
}

Источник

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}	source	объект	✔️ Да	Никакой

Конфигурация {entity}.source подключает сущность, предоставляемую API, и ее базовый объект базы данных. Это свойство указывает таблицу базы данных, представление или хранимую процедуру, представляющую сущность, устанавливая прямую связь для извлечения и обработки данных.

Для простых сценариев, когда сущность сопоставляется непосредственно с одной таблицей базы данных, исходное свойство должно иметь только имя этого объекта базы данных. Эта простота упрощает быструю настройку распространенных вариантов использования: "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>
        }
      }
    }
  }
}

Свойства

	Обязательно	Тип
object	✔️ Да	струна
type	✔️ Да	строка перечисления
parameters	❌ Нет	объект
key-fields	❌ Нет	массив строк

Примеры

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.GetUsersproc.

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 необязательно для хранимых процедур.

Объект

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.source	object	струна	✔️ Да	Никакой

Имя используемого объекта базы данных. Если объект принадлежит схеме 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"
      }
    }
  }
}

Тип (сущности)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.source	type	струна	✔️ Да	Никакой

Свойство type определяет тип объекта базы данных, в том числе view, tableи stored-procedure. Это свойство является обязательным и не имеет значения по умолчанию.

Формат

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

Значения

Ценность	Описание
table	Представляет таблицу.
stored-procedure	Представляет хранимую процедуру.
view	Представляет представление.

Примеры

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

Ключевые поля

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.source	key-fields	массив строк	❌ Нет	Никакой

Свойство {entity}.key-fields особенно необходимо для сущностей, поддерживаемых представлениями, поэтому построитель данных знает, как определить и вернуть один элемент. Если type задано значение view без указания key-fields, подсистема отказывается запускаться. Это свойство допускается с таблицами и хранимыми процедурами, но в этих случаях оно не используется.

Важный

Это свойство требуется, если тип объекта является view.

Формат

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

Параметры

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.source	parameters	объект	❌ Нет	Никакой

Свойство parameters в entities.{entity}.source используется для сущностей, поддерживаемых хранимыми процедурами. Он обеспечивает надлежащее сопоставление имен параметров и типов данных, необходимых хранимой процедуре.

Важный

Свойство parametersобязательно, если type объекта stored-procedure и требуется параметр.

Формат

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

Разрешения

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}	permissions	объект	✔️ Да	Никакой

В этом разделе определяется, кто может получить доступ к связанной сущности и какие действия разрешены. Разрешения определяются с точки зрения ролей и операций CRUD: create, read, updateи delete. В разделе permissions указывается, какие роли могут получить доступ к связанной сущности и использовать какие действия.

Формат

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

Действие	Описание
create	Позволяет создавать запись в сущности.
read	Позволяет считывать или извлекать записи из сущности.
update	Позволяет обновлять существующие записи в сущности.
delete	Разрешает удаление записей из сущности.
execute	Позволяет выполнять хранимую процедуру или операцию.
*	Предоставляет все применимые операции CRUD.

Примеры

пример 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.

Другой способ выражения той же логики:

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

Учитывая, что exclude имеет приоритет над include, указывая exclude: ["*"] означает, что все поля исключены, даже те, в include. Таким образом, на первый взгляд, эта конфигурация может препятствовать доступу к любым полям.

обратной: если намерение предоставить доступ только к полям Id и Name, то более четко и надежно указать только эти поля в разделе include без использования подстановочного знака исключения:

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

Свойства

	Обязательно	Тип
role	✔️ Да	струна
actions (string-array) или actions (объект-массив)	✔️ Да	объект или массив строк

Роль

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.permissions	role	струна	✔️ Да	Никакой

Строка, содержащая имя роли, к которой применяется определенное разрешение. Роли задают контекст разрешений, в котором должен выполняться запрос. Для каждой сущности, определенной в конфигурации среды выполнения, можно определить набор ролей и связанных разрешений, определяющих способ доступа к сущности с помощью конечных точек REST и GraphQL. Роли не являются аддитивным.

Построитель данных оценивает запросы в контексте одной роли:

Роль	Описание
anonymous	Маркер доступа не представлен
authenticated	Представлен допустимый маркер доступа
<custom-role>	Представлен допустимый маркер доступа, а заголовок HTTP X-MS-API-ROLE указывает роль, представленную в маркере.

Формат

{
  "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, указав роль пользователя, которая также содержится в утверждении ролей маркера доступа. Ниже приведены примеры запросов GET к сущности User, включая маркер носителя авторизации и заголовок X-MS-API-ROLE, на базе конечной точки REST /apilocalhost с использованием разных языков.

HTTP

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

C#

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

JavaScript/TypeScript

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

Python

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())

Действия (string-array)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.permissions	actions	oneOf [string, array]	✔️ Да	Никакой

Массив строковых значений, подробных сведений о том, какие операции разрешены для связанной роли. Для объектов базы данных table и view роли могут использовать любое сочетание create, read, updateили delete действий. Для хранимых процедур роли могут иметь только действие execute.

Действие	Операция SQL
*	Подстановочный знак, включая выполнение
create	Вставка одной или нескольких строк
read	Выберите одну или несколько строк
update	Изменение одной или нескольких строк
delete	Удаление одной или нескольких строк
execute	Запускает хранимую процедуру

Заметка

Для хранимых процедур действие подстановочного знака (*) расширяется только на действие execute. Для таблиц и представлений он расширяется до create, read, updateи delete.

Примеры

В этом примере предоставляются разрешения 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"]
        }
      ]
    }
  }
}

Действия (объект-массив)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.permissions	actions	массив строк	✔️ Да	Никакой

Массив объектов действий, подробных сведений о разрешенных операциях для связанной роли. Для объектов table и view роли могут использовать любое сочетание create, read, updateили delete. Для хранимых процедур допускается только execute.

Заметка

Для хранимых процедур действие подстановочного знака (*) расширяется только до execute. Для таблиц и представлений он расширяется до create, read, updateи delete.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
action	✔️ Да	струна	Никакой
fields	❌ Нет	массив строк	Никакой
policy	❌ Нет	объект	Никакой

Пример

В этом примере предоставляется только read разрешение на роль auditor сущности User с ограничениями полей и политик.

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

Действие

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.permissions.actions[]	action	струна	✔️ Да	Никакой

Указывает определенную операцию, разрешенную для объекта базы данных.

Значения

	Таблицы	Представления	Хранимые процедуры	Описание
create	✔️ Да	✔️ Да	❌ Нет	Создание новых элементов
read	✔️ Да	✔️ Да	❌ Нет	Чтение существующих элементов
update	✔️ Да	✔️ Да	❌ Нет	Обновление или замена элементов
delete	✔️ Да	✔️ Да	❌ Нет	Удаление элементов
execute	❌ Нет	❌ Нет	✔️ Да	Выполнение программных операций

Формат

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

Поля

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.permissions.actions[]	fields	объект	❌ Нет	Никакой

Детализированные спецификации, в которых определенные поля разрешены для объекта базы данных. Объект fields содержит два свойства и includeexcludeопределяет, какие столбцы базы данных разрешены или ограничены для заданного действия.

Формат

{
  "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 роли считывать все поля из User сущности, кроме IsAdminтого, что позволяет создавать новые User записи.

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

Политика

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.permissions.actions[]	policy	объект	❌ Нет	Никакой

Раздел policy , определенный для каждого действия, задает правила безопасности на уровне элементов, ограничивающие результаты, возвращаемые из запроса. Подраздел database обозначает выражение, подобное OData, вычисляемое во время выполнения запроса, которое построитель данных преобразуется в предикат запроса.

Формат

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

Базовый пример

В этом примере действие для adultReader роли ограниченоread, чтобы возвращаются только пользователи старше 18:

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

База данных

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.permissions[].actions[].policy	database	струна	✔️ Да	Никакой

Описание

Свойство database в политике определяет выражение OData, подобное конструктору данных, преобразуется в предикат SQL для фильтрации результатов во время выполнения запроса. Это выражение должно оцениваться для true возвращаемых строк. Рассмотрим пример.

• @item.Age gt 18 может преобразоваться в WHERE Users.Age > 18.
• @claims.userId eq @item.Id ограничивает результаты строками, в которых идентификатор пользователя из утверждений соответствует полю Id .

Директивы

• @claims: доступ к утверждению из проверенного маркера доступа.
• @item: представляет поле сущности, для которой определена политика.

Заметка

При использовании проверки подлинности статических веб-приложений Azure (EasyAuth) доступны только определенные типы утверждений (identityProvider, userId, , userDetails). userRoles

Поддерживаемые операторы OData, такие как

Выражение поддерживает такие операторы, как:

• Логический: and, ornot
• Сравнение: eq, , gtlt
• Унарное числовое отрицание: -

Например, "@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. При необходимости используйте сопоставления с полями псевдонимов.

Примеры

Рассмотрим сущность, именуемую User в конфигурации API данных, которая использует политики для ограничения доступа на основе возраста и удостоверения пользователя.

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. Доступ на основе утверждений

Эта конфигурация использует утверждение для ограничения selfReader роли, чтобы пользователи могли только читать свои собственные записи, если их userId утверждение соответствует Id полю.

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

GraphQL (сущности)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}	graphql	объект	❌ Нет	Никакой

Этот объект определяет поведение GraphQL сущности.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
enabled	❌ Нет	булев	Никакой
type	❌ Нет	строка или объект	Никакой
operation	❌ Нет	строка перечисления	Никакой

Примеры

Эти два примера функционально эквивалентны, включив GraphQL для User сущности с параметрами по умолчанию:

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

В этом примере определена Userсущность, указывающая, что мы имеем дело с данными пользователя. Конфигурация сущности User в сегменте GraphQL указывает, как она должна быть представлена и взаимодействовать с ней в схеме GraphQL.

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

Тип (сущность GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.graphql	type	объект	❌ Нет	{entity-name}

Это свойство определяет соглашение об именовании сущности в схеме GraphQL. Он задает формы сингулярного и множественного числа, обеспечивая детализированный контроль над удобочитаемостью схемы и взаимодействием с пользователем.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
singular	❌ Нет	струна	Никакой
plural	❌ Нет	струна	N/A (по умолчанию используется единственное значение)

Примеры

Если plural отсутствует или опущен (например, скалярное значение), построитель данных попытается включить автоматическое число имен с помощью правил английского языка для плюрализации.

Явные имена сингулярного и множественного числа:

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

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.graphql	operation	строка перечисления	❌ Нет	мутация

Для сущностей, сопоставленных с хранимыми процедурами, свойство указывает, operation отображается ли операция GraphQL в Query разделе или Mutation типе. Этот параметр упорядочивает схему логически без влияния на функциональные возможности.

Заметка

Если {entity}.type задано значение stored-procedure, создается автоматически новый тип executeXXX GraphQL. Свойство operation определяет, помещается ли этот тип в илиMutationQuery. Функциональное влияние на выбранное значение не влияет.

Формат

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

Значения

Ценность	Описание
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
}

Заметка

Свойство operation влияет только на размещение операции GraphQL в схеме; она не изменяет поведение операции.

Включено (сущность GraphQL)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.graphql	enabled	булев	❌ Нет	Истинный

Включает или отключает конечную точку GraphQL. Определяет доступность сущности с помощью конечных точек GraphQL. Переключение свойства enabled позволяет разработчикам выборочно предоставлять сущности из схемы GraphQL.

Формат

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

REST (сущности)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}	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"]>
      }
    }
  }
}

Свойства

Свойство	Обязательно	Тип	По умолчанию
enabled	✔️ Да	булев	Истинный
path	❌ Нет	струна	/<entity-name>
methods	❌ Нет	массив строк	ПОЛУЧИТЬ

Примеры

Эти два примера функционально эквивалентны.

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

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

Ниже приведен еще один пример конфигурации REST для сущности.

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

Включено (сущность REST)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.rest	enabled	булев	❌ Нет	Истинный

Это свойство выступает в качестве переключателя для видимости сущностей в REST API. Задав свойство enabled для true или false, разработчики могут управлять доступом к определенным сущностям, позволяя специализированной поверхности API, которая соответствует требованиям к безопасности приложений и функциональным возможностям.

Формат

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

Путь (сущность REST)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.rest	path	струна	❌ Нет	Никакой

Свойство path указывает сегмент URI, используемый для доступа к сущности через REST API. Эта настройка позволяет более описательные или упрощенные пути конечной точки за пределами имени сущности по умолчанию, повышая навигацию ПО API и интеграцию на стороне клиента. По умолчанию путь имеет значение /<entity-name>.

Формат

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

Примеры

В этом примере предоставляется сущность Author с помощью конечной точки /auth.

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

Методы (сущность REST)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.rest	methods	массив строк	❌ Нет	Никакой

Применимо специально к хранимым процедурам, свойство methods определяет, какие HTTP-команды (например, GET, POST) процедура может реагировать. Методы позволяют точно контролировать способ предоставления хранимых процедур через REST API, обеспечивая совместимость со стандартами RESTful и ожиданиями клиентов. В этом разделе подчеркивается приверженность платформы к гибкости и управлению разработчиком, что позволяет точно и интуитивно понятно разрабатывать API, адаптированные к конкретным потребностям каждого приложения.

Если опущен или отсутствует, methods по умолчанию POST.

Формат

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

Значения

Ниже приведен список разрешенных значений для этого свойства:

	Описание
get	Предоставляет HTTP-запросы GET
post	Предоставляет HTTP-запросы 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" ]
      }
    }
  }
}

Сопоставления (сущности)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}	mappings	объект	❌ Нет	Никакой

раздел mappings позволяет настраивать псевдонимы или имена, предоставляемые для полей объектов базы данных. Настроенные имена применяются как к конечным точкам GraphQL, так и к конечным точкам REST.

Важный

Для сущностей с поддержкой GraphQL настроенное имя должно соответствовать требованиям именования GraphQL. Дополнительные сведения см. в спецификации имен GraphQL.

Формат

{
  "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 предоставляется как status в конечных точках REST и GraphQL.

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

Ниже приведен еще один пример сопоставлений.

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

сопоставления: объект mappings связывает поля базы данных (BookID, BookTitle, AuthorName) с более понятными или стандартизированными именами (id, title, author), которые используются внешне. Этот псевдоним служит для нескольких целей:

• Ясность и согласованность. Он позволяет использовать четкое и согласованное именование в API независимо от базовой схемы базы данных. Например, BookID в базе данных представляется как id в API, что делает его более интуитивно понятным для разработчиков, взаимодействующих с конечной точкой.

• соответствие GraphQL. Предоставляя механизм для имен полей псевдонимов, он гарантирует, что имена, предоставляемые через интерфейс GraphQL, соответствуют требованиям к именованию GraphQL. Внимание к именам важно, так как GraphQL имеет строгие правила о именах (например, пробелы не должны начинаться с буквы или подчеркивания и т. д.). Например, если имя поля базы данных не соответствует этим критериям, его можно псевдонимировать в соответствующее имя с помощью сопоставлений.

• гибкость. Этот псевдоним добавляет слой абстракции между схемой базы данных и API, что позволяет вносить изменения в одну из них без необходимости вносить изменения в другую. Например, изменение имени поля в базе данных не требует обновления документации по API или клиентского кода, если сопоставление остается согласованным.

• имя поля. Сопоставление позволяет скрыть имена полей, что может помочь предотвратить вывод несанкционированных пользователей конфиденциальной информации о схеме базы данных или характере хранимых данных.

• защита конфиденциальной информации: путем переименования полей можно также защитить собственные имена или бизнес-логику, которые могут быть намечены с помощью исходных имен полей базы данных.

Связи (сущности)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}	relationships	объект	❌ Нет	Никакой

В этом разделе приведен набор определений связей, которые сопоставляют, как сущности связаны с другими предоставляемыми сущностями. Эти определения связей также могут дополнительно включать сведения о базовых объектах базы данных, используемых для поддержки и принудительного применения связей. Объекты, определенные в этом разделе, предоставляются в виде полей GraphQL в связанной сущности. Дополнительные сведения см. в разделе связи построителя данных.

Заметка

Связи относятся только к запросам GraphQL. Конечные точки REST получают доступ только к одной сущности за раз и не могут возвращать вложенные типы.

В разделе relationships описывается взаимодействие сущностей в построителе API данных, детализация связей и потенциальная поддержка баз данных для этих связей. Свойство relationship-name для каждой связи является обязательным и должно быть уникальным для всех связей для данной сущности. Пользовательские имена обеспечивают четкие, идентифицируемые подключения и поддерживают целостность схемы GraphQL, созданной из этих конфигураций.

Связь	Мощность	Пример
Один ко многим	many	Одна сущность категории может относиться ко многим сущностям todo
"многие к одному"	one	Многие сущности todo могут относиться к одной сущности категории
Многие ко многим	many	Одна сущность todo может относиться ко многим пользовательским сущностям, и одна сущность пользователя может относиться ко многим сущностям todo

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
cardinality	✔️ Да	строка перечисления	Никакой
target.entity	✔️ Да	струна	Никакой
source.fields	❌ Нет	массив строк	Никакой
target.fields	❌ Нет	массив строк	Никакой
linking.<object-or-entity>	❌ Нет	струна	Никакой
linking.source.fields	❌ Нет	массив строк	Никакой
linking.target.fields	❌ Нет	массив строк	Никакой

Примеры

При рассмотрении отношений лучше сравнить различия между одно ко многим, ко многим, а также отношениями "многие ко многим".

Один ко многим

Во-первых, рассмотрим пример связи с предоставленной сущностью Category имеет отношение одно ко многим с сущностью Book. Здесь для кратности задано значение many. Каждая Category может иметь несколько связанных Book сущностей, в то время как каждая Book сущность связана только с одной сущностью 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]!
}

Многие к одному

Далее рассмотрим "многие ко одному", который задает кратность one. Доступная Book сущность может иметь одну связанную 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]!
}

Мощность

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.relationships	cardinality	струна	✔️ Да	Никакой

Указывает, связана ли текущая исходная сущность только с одним экземпляром целевой сущности или несколькими.

Значения

Ниже приведен список разрешенных значений для этого свойства:

	Описание
one	Источник относится только к одной записи из целевого объекта.
many	Источник может относиться к записям нулевого ко многим из целевого объекта.

Целевая сущность

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.relationships	target.entity	струна	✔️ Да	Никакой

Имя сущности, определенной в другом месте конфигурации, которая является целью связи.

Исходные поля

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.relationships	source.fields	массив	❌ Нет	Никакой

Необязательный параметр для определения поля, используемого для сопоставления в источнике сущности, используемой для подключения к связанному элементу в целевой сущности.

Кончик

Это поле не требуется, если внешний ключ ограничения для базы данных между двумя объектами базы данных, которые можно использовать для автоматического вывода связи.

Целевые поля

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.relationships	target.fields	массив	❌ Нет	Никакой

Необязательный параметр, определяющий поле, используемое для сопоставления в целевом объекте , используемом для подключения к связанному элементу в исходной сущности.

Кончик

Это поле не требуется, если внешний ключ ограничения для базы данных между двумя объектами базы данных, которые можно использовать для автоматического вывода связи.

Связывание объекта или сущности

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.relationships	linking.object	струна	❌ Нет	Никакой

Для связей "многие ко многим" имя объекта базы данных или сущности, содержащей данные, необходимые для определения связи между двумя другими сущностями.

Связывание исходных полей

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.relationships	linking.source.fields	массив	❌ Нет	Никакой

Имя объекта базы данных или поля сущности, связанного с исходной сущностью.

Связывание целевых полей

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.relationships	linking.target.fields	массив	❌ Нет	Никакой

Имя объекта базы данных или поля сущности, связанного с целевой сущностью.

Кэш (сущности)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.cache	enabled	булев	❌ Нет	Ложный

Включает и настраивает кэширование для сущности.

Формат

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

Свойства

Свойство	Обязательно	Тип	По умолчанию
enabled	❌ Нет	булев	Ложный
ttl-seconds	❌ Нет	целое число	5

Примеры

В этом примере кэш включен и элементы истекают через 30 секунд.

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

Включено (сущность кэша)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.{entity}.cache	enabled	булев	❌ Нет	Ложный

Включает кэширование для сущности.

Поддержка объектов базы данных

Тип объекта	Поддержка кэша
Стол	✅ Да
Вид	✅ Да
Хранимая процедура	✖️ Нет
Контейнер	✖️ Нет

Поддержка заголовка HTTP

Заголовок запроса	Поддержка кэша
no-cache	✖️ Нет
no-store	✖️ Нет
max-age	✖️ Нет
public	✖️ Нет
private	✖️ Нет
etag	✖️ Нет

Формат

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

Примеры

В этом примере кэш отключен.

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

TTL в секундах (сущность кэша)

---

Родитель	Свойство	Тип	Обязательно	По умолчанию
entities.cache	ttl-seconds	целое число	❌ Нет	5

Настраивает значение времени в реальном времени (TTL) в секундах для кэшированных элементов. По истечении этого времени элементы автоматически удаляются из кэша. Значение по умолчанию — 5 секунд.

Формат

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

Примеры

В этом примере кэш включен, а срок действия элементов истекает через 15 секунд. Если этот параметр не указан, этот параметр наследует глобальный параметр или значение по умолчанию.

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

Связанное содержимое

• Справочник по функциям
• справочник по интерфейсу командной строки