Поделиться через

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

  • Статья

Для обработчика 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 SQL 2016
sqldw Хранилище данных SQL Azure Никакой
postgresql PostgreSQL версия 11
mysql MySQL v8
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$

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

Товары второго сорта
First 2
Second 4
третий 8
четвертый 16
Пятый 32

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
  }
}
    • Типичный формат строки подключения: "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

  • postgresql

    "data-source": {
  "database-type": "postgresql",
  "connection-string": "$env('my-connection-string')"
}
    • Типичный формат строки подключения: "Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"

  • mysql

    "data-source": {
  "database-type": "mysql",
  "connection-string": "$env('my-connection-string')"
}
    • Типичный формат строки подключения: "Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"

  • 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"
  }
}
    • Типичный формат строки подключения: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

  • cosmosdb_postgresql

    "data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}
    • Типичный формат строки подключения: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Заметка

Указанные параметры, такие как 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 см. в справочнике по ВЕБ-документации MDN CORS.

Формат

{
  "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, который может просить свои утверждения и свойства.

поддержка веб-маркеров JSON в построителе API данных.

Ниже приведены примеры свойства 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 с использованием разных языков.

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

Действия (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 объект ❌ Нет Никакой

Детализированные спецификации, в которых определенные поля разрешены для объекта базы данных. Конфигурация роли — это тип объекта с двумя внутренними свойствами, include и exclude. Эти значения поддерживают детализированное определение того, какие столбцы базы данных (поля) разрешены в разделе fields.

Формат

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

Примеры

В этом примере роль anonymous может читаться из всех полей, кроме id, но при создании элемента можно использовать все поля.

{
  "entities": {
    "Author": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": [ "*" ],
                "exclude": [ "id" ]
              }
            },
            { "action": "create" }
          ]
        }
      ]
    }
  }
}

Включите и исключите совместную работу. Подстановочный знак * в разделе include указывает все поля. Поля, отмеченные в разделе exclude, имеют приоритет над полями, отмеченным в разделе include. Определение преобразуется в включают все поля, кроме поля "last_updated".

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ],
            // Include All Except Specific Fields
            "fields": {
              "include": [ "*" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "authenticated",
            "actions": [ "read", "update" ],
            // Explicit Include and Exclude
            "fields": {
              "include": [ "id", "title", "secret-field" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "author",
            "actions": [ "*" ],
            // Include All With No Exclusions (default)
            "fields": {
              "include": ["*"],
              "exclude": []
            }
        }
    ]
}

Политика

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

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

Формат

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

Свойства

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

Описание

Политика database: выражение OData, которое преобразуется в предикат запроса, вычисляется, включая операторы, такие как eq, ltи gt. Чтобы результаты возвращались для запроса, предикат запроса, разрешенный из политики базы данных, должен оцениваться как true при выполнении в базе данных.

Пример политики элементов Предикат
@item.OwnerId eq 2000 WHERE Table.OwnerId = 2000
@item.OwnerId gt 2000 WHERE Table.OwnerId > 2000
@item.OwnerId lt 2000 WHERE Table.OwnerId < 2000

predicate — это выражение, которое оценивается как TRUE или FALSE. Предикаты используются в условии поиска предложений WHERE и предложениях HAVING, условий соединения предложений FROM и других конструкций, где требуется логическое значение. (Документы Microsoft Learn)

Политика базы данных

При создании выражения политики базы данных можно использовать два типа директив:

Директива Описание
@claims Доступ к утверждению в проверенном маркере доступа, предоставленном в запросе
@item Представляет поле сущности, для которой определена политика базы данных

Заметка

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

Ниже приведены несколько примеров политик базы данных:

  • @claims.userId eq @item.OwnerId
  • @claims.userId gt @item.OwnerId
  • @claims.userId lt @item.OwnerId

Построитель API данных сравнивает значение утверждения UserId со значением поля базы данных OwnerId. Результат полезных данных содержит только записи, которые выполняют как метаданные запроса, так и выражение политики базы данных.

Ограничения

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

Политики баз данных не препятствуют выполнению запросов в базе данных. Это связано с тем, что они разрешаются в виде предикатов в созданных запросах, передаваемых в ядро СУБД.

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

Поддерживаемые операторы OData, такие как
Оператор Описание Пример синтаксиса
and Логический И "@item.status eq 'active' and @item.age gt 18"
or Логическое ИЛИ "@item.region eq 'US' or @item.region eq 'EU'"
eq Равно "@item.type eq 'employee'"
gt Больше "@item.salary gt 50000"
lt Менее "@item.experience lt 5"

Дополнительные сведения см. в двоичных операторах.

Оператор Описание Пример синтаксиса
- Negate (числовой) "@item.balance lt -100"
not Логическое негейт (NOT) "not @item.status eq 'inactive'"

Дополнительные сведения см. в унарных операторов.

Ограничения имени поля сущности
  • правила: должно начинаться с буквы или подчеркивания (_), за которым следует до 127 букв, символов подчеркивания (_) или цифр (0-9).
  • влияние. Поля, не входящие в эти правила, нельзя напрямую использовать в политиках баз данных.
  • решения: используйте раздел mappings для создания псевдонимов для полей, которые не соответствуют этим соглашениям об именовании; Сопоставления гарантируют, что все поля можно включить в выражения политики.
Использование mappings для несообразующих полей

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

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

В этом примере field-1-name — это имя исходного поля базы данных, которое не соответствует соглашениям об именовании OData. Создание карты с field-1-name и field-1-alias позволяет ссылаться на это поле в выражениях политики базы данных без проблем. Этот подход не только помогает придерживаться соглашений об именовании OData, но и повышает четкость и доступность модели данных в конечных точках GraphQL и RESTful.

Примеры

Рассмотрим сущность с именем Employee в конфигурации API данных, которая использует как директивы утверждений, так и элементов. Он обеспечивает безопасное управление доступом к данным на основе ролей пользователей и владения сущностями:

{
  "entities": {
    "Employee": {
      "source": {
        "object": "HRUNITS",
        "type": "table",
        "key-fields": ["employee NUM"],
        "parameters": {}
      },
      "mappings": {
        "employee NUM": "EmployeeId",
        "employee Name": "EmployeeName",
        "department COID": "DepartmentId"
      },
      "policy": {
        "database": "@claims.role eq 'HR' or @claims.userId eq @item.EmployeeId"
      }
    }
  }
}

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

конфигурация источника: определяет HRUNITS в базе данных с employee NUM в качестве ключевого поля.

сопоставления: псевдонимы используются для сопоставления employee NUM, employee Nameи department COID с EmployeeId, EmployeeNameи DepartmentIdсоответственно, упрощая имена полей и потенциально маскируя сведения о схеме конфиденциальной базы данных.

приложения политики. В разделе policy применяется политика базы данных с помощью выражения OData, аналогичного OData. Эта политика ограничивает доступ к данным пользователям с ролью управления персоналом (@claims.role eq 'HR') или пользователям, UserId утверждения которых совпадают EmployeeId — псевдоним поля в базе данных (@claims.userId eq @item.EmployeeId). Это гарантирует, что сотрудники могут получить доступ только к собственным записям, если они не принадлежат отделу кадров. Политики могут применять безопасность на уровне строк на основе динамических условий.

База данных

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

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

Формат

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

Это свойство обозначает выражение политики базы данных, которое вычисляется во время выполнения запроса. Строка политики — это выражение OData, которое преобразуется в предикаты запроса, вычисляемого базой данных. Например, выражение политики @item.OwnerId eq 2000 преобразуется в предикат запроса WHERE <schema>.<object-name>.OwnerId = 2000.

Заметка

предиката — это выражение, которое позволяет , или . Предикаты используются в:

  • Условие поиска предложений WHERE
  • Условие поиска предложений FROM
  • Условия соединения предложений FROM
  • Другие конструкции, в которых требуется логическое значение.

Дополнительные сведения см. в предикаты.

Чтобы результаты возвращались для запроса, предикат запроса, разрешенный из политики базы данных, должен оцениваться как true при выполнении в базе данных.

При создании выражения политики базы данных можно использовать два типа директив:

Описание
@claims Обращается к утверждению в проверенном маркере доступа, предоставленном в запросе.
@item Представляет поле сущности, для которой определена политика базы данных

Заметка

Ограниченное количество типов утверждений доступно для использования в политиках базы данных при настройке проверки подлинности статических веб-приложений Azure (EasyAuth). К таким типам утверждений относятся: identityProvider, userId, userDetailsи userRoles. Дополнительные сведения см. в данных субъекта-клиента статических веб-приложений Azure.

Примеры

Например, базовое выражение политики может оценить, является ли определенное поле истинным в таблице. В этом примере вычисляется, soft_delete ли поле false.

{
  "entities": {
    "Manuscripts": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.soft_delete eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Предикаты также могут оценивать как claims, так и item типы директив. В этом примере извлекает поле UserId из маркера доступа и сравнивает его с полем owner_id в целевой таблице базы данных.

{
  "entities": {
    "Manuscript": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.userId eq @item.owner_id"
              }
            }
          ]
        }
      ]
    }
  }
}

Ограничения

  • Политики баз данных поддерживаются для таблиц и представлений. Хранимые процедуры нельзя настроить с политиками.
  • Политики баз данных нельзя использовать для предотвращения выполнения запроса в базе данных. Это ограничение связано с тем, что политики базы данных разрешаются в виде предикатов запросов в созданных запросах базы данных. Ядро СУБД в конечном счете оценивает эти запросы.
  • Политики баз данных поддерживаются только для actionscreate, read, updateи delete.
  • Синтаксис выражения OData политики базы данных поддерживает только эти сценарии.
    • Двоичные операторы, включая, но не ограничиваются; and, or, eq, gtи lt. Дополнительные сведения см. в разделе BinaryOperatorKind.
    • Унарные операторы, такие как - (неуправляемые) и not операторы. Дополнительные сведения см. в разделе UnaryOperatorKind.
  • Политики баз данных также имеют ограничения, связанные с именами полей.
    • Имена полей сущностей, начинающиеся с буквы или подчеркивания, за которым следует не более 127 букв, символов подчеркивания или цифр.
    • Это требование соответствует спецификации OData. Дополнительные сведения см. в разделе языке общего определения схемы OData.

Кончик

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

GraphQL (сущности)

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

Этот объект определяет, включен ли GraphQL и имя[s], используемое для предоставления сущности в виде типа GraphQL. Этот объект является необязательным и используется только в том случае, если имя или параметры по умолчанию недостаточно.

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

Формат

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

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <boolean>,
        "type": <string-or-object>,
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Свойства

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

Примеры

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

{
  "entities": {
    "Author": {
      "graphql": true
    }
  }
}

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

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

включено свойство: сущность Book доступна с помощью GraphQL ("enabled": true), что означает, что разработчики и пользователи могут запрашивать или изменять данные книги с помощью операций GraphQL.

свойству Type: сущность представлена с уникальным именем "Book" и именем множественного числа, "Books" в схеме GraphQL. Это различие гарантирует, что при запросе одной книги или нескольких книг схема предлагает интуитивно именованные типы (Book для одной записи, Books для списка), повышая удобство использования API.

свойство Operation: операция имеет значение "query", указывая, что основное взаимодействие с сущностью Book через GraphQL предназначено для запроса (извлечения) данных, а не изменения (создания, обновления или удаления). Эта настройка соответствует типичным шаблонам использования, в которых данные книги чаще считываются, чем изменены.

{
  "entities": {
    "Book": {
      ...
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      ...
    }
  }
}

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

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

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

Формат

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

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

Свойства

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

Примеры

Для еще большего контроля над типом GraphQL можно настроить, как имя сингулярного и множественного числа представлено независимо.

Если plural отсутствует или опущен (например, скалярное значение) построитель данных пытается включить автоматическое число имен, следуя правилам английского языка для плюрализации (например, https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

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

{
  "entities": {
    "Author": {
      "graphql": {
        "type": "bookauthor"
      }
    }
  }
}

Если вы решили явно указать имена, используйте свойства type.singular и type.plural. Этот пример явно задает оба имени.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": {
          "singular": "bookauthor",
          "plural": "bookauthors"
        }
      }
    }
  }
}

Оба примера функционально эквивалентны. Они возвращают одинаковые выходные данные JSON для запроса GraphQL, использующего имя сущности bookauthors.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

{
  "data": {
    "bookauthors": {
      "items": [
        {
          "first_name": "Henry",
          "last_name": "Ross"
        },
        {
          "first_name": "Jacob",
          "last_name": "Hancock"
        },
        ...
      ]
    }
  }
}

Операция (сущность GraphQL)

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

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

Заметка

Сущность указывается для хранимой процедуры, задав значение свойства {entity}.type значение stored-procedure. В случае хранимой процедуры создается автоматически новый тип GraphQL executeXXXX. Однако свойство operation позволяет разработчику совместно использовать расположение этого типа в mutation или query частях схемы. Это свойство позволяет использовать hygene схемы и не оказывает функционального влияния независимо от operation значения.

Если отсутствует, operation по умолчанию mutation.

Формат

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

Значения

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

Описание
query Базовая хранимая процедура предоставляется в виде запроса
mutation Базовая хранимая процедура предоставляется как мутация

Примеры

Если operationmutation, схема GraphQL будет выглядеть следующим образом:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Если operationquery, схема GraphQL будет выглядеть следующим образом:

Схема GraphQL будет выглядеть следующим образом:

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Заметка

Свойство 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 булев ❌ Нет Ложный

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

Формат

You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:

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

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

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