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

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

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

Свойства источника данных

Свойства среды выполнения

Свойства сущностей

Schema

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

Format

{
  "$schema": <string>
}

Example

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json"
}

Versioning

Файлы схемы доступны по определенным 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

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

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

Format

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

Несколько правил конфигурации

• Каждый файл конфигурации должен содержать свойство data-source.
• Каждый файл конфигурации должен содержать entities свойство (или autoentities).
• Конфигурация верхнего уровня должна включать runtime.
• Дочерние конфигурации могут включать в себя runtime, но построитель API данных игнорирует его.
• Дочерние файлы конфигурации могут включать собственные дочерние файлы.
• Файлы конфигурации можно упорядочить в вложенные папки.
• Имена сущностей должны быть уникальными во всех файлах конфигурации.
• Связи между сущностями в разных файлах конфигурации не поддерживаются.

Examples

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

Автоматическое заполнение

В autoentities этом разделе определяются правила на основе шаблонов, которые автоматически предоставляют соответствующие объекты базы данных в виде сущностей DAB при запуске. Каждый ключ в объекте — это именованное определение, содержащее шаблоны, шаблон и разрешения.

Когда autoentities он присутствует, раздел entities больше не требуется. Схема конфигурации разрешает либо autoentities (или и то, и entities другое). Если оба имеются, явно определенные сущности имеют приоритет над автоматическими совпадениями с одинаковым именем.

Format

{
  "autoentities": {
    "<definition-name>": {
      "patterns": {
        "include": [ "<string>" ],
        "exclude": [ "<string>" ],
        "name": "<string>"
      },
      "template": {
        "mcp": { "dml-tools": <boolean> },
        "rest": { "enabled": <boolean> },
        "graphql": { "enabled": <boolean> },
        "health": { "enabled": <boolean> },
        "cache": {
          "enabled": <boolean>,
          "ttl-seconds": <integer>,
          "level": "<string>"
        }
      },
      "permissions": [
        {
          "role": "<string>",
          "actions": [ { "action": "<string>" } ]
        }
      ]
    }
  }
}

Свойства

Example

{
  "autoentities": {
    "my-def": {
      "patterns": {
        "include": [ "dbo.%" ],
        "exclude": [ "dbo.internal%" ],
        "name": "{schema}_{object}"
      },
      "template": {
        "rest": { "enabled": true },
        "graphql": { "enabled": true },
        "cache": { "enabled": true, "ttl-seconds": 30, "level": "l1l2" }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ { "action": "read" } ] }
      ]
    }
  }
}

При этой конфигурации каждая таблица и представление схемы dbo (за исключением совпадающих dbo.internal%) автоматически предоставляется как сущность DAB. Каждая сущность называется с помощью {schema}_{object} шаблона (например, dbo_Productsс поддержкой REST и GraphQL), использует кэширование с 30-секундным временем жизни (TTL) и предоставляет read доступ к anonymous роли.

Azure Key Vault

Настраивает интеграцию Azure Key Vault для управления секретами. При наличии endpoint свойства требуется.

Вложенные свойства

Чтобы ссылаться на секреты, хранящиеся в Azure Key Vault, используйте функцию @akv() в значениях конфигурации. Построитель API данных разрешает эти ссылки при запуске с помощью настроенной конечной точки.

Format

{
  "azure-key-vault": {
    "endpoint": "<string>",
    "retry-policy": {
      "mode": <"exponential"> (default) | <"fixed">,
      "max-count": <integer; default: 3>,
      "delay-seconds": <integer; default: 1>,
      "max-delay-seconds": <integer; default: 60>,
      "network-timeout-seconds": <integer; default: 60>
    }
  }
}

Example

{
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 120,
      "network-timeout-seconds": 90
    }
  },
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('sql-connection-string')"
  }
}