Устранение неполадок с использованием построителя API данных для баз данных Azure

В этой статье приведены решения распространенных ошибок, которые могут возникнуть при использовании построителя API данных для баз данных Azure.

Универсальная конечная точка: ошибка HTTP 400 "Недопустимый запрос"

В следующих разделах описываются причины и решения ошибки HTTP 400 "Недопустимый запрос".

Недопустимая конечная точка API-конструктора данных

Основная часть компонента пути URL сопоставляется с конечной точкой REST или GraphQL конструктора Data API. Если база компонента пути URL-адреса не соответствует значению, заданному в конфигурации среды выполнения построителя данных, построитель данных возвращает ошибку HTTP 400 "Недопустимый запрос".

Вы можете настроить корневые пути для конечных точек GraphQL и REST в runtime разделе конфигурации среды выполнения построителя данных. Для создания URL-путей для конечных точек REST и GraphQL необходимо использовать значения.

Например, следующие конфигурации задают /api в качестве корневого пути конечной точки REST и /graphql в качестве корневого пути конечной точки GraphQL.

"runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "...",
}

Таким образом, значения, которые необходимо использовать в начале пути URL для конечных точек REST и GraphQL, являются следующими:

/api/<entity>

/graphql

Примечание.

При использовании построителя API данных со статическими веб-приложениями и функции "Подключения к базе данных", путь URL-адреса начинается с /data-api. После этого значения можно добавить значение требуемой конечной точки. Например, /data-api/api/<entity> для REST и /data-api/graphql GraphQL.

Проблема с конфигурацией подключений к базам данных в Static Web Apps.

При использовании Data API Builder с функцией подключения к базе данных в статических веб-приложениях возникает ошибка "Код состояния ответа не указывает на успех: 400 (Bad Request)".

{"Message":"{\u0022Message\u0022:\u0022Response status code does not indicate success: 400 (Bad Request).\u0022,\u0022ActivityId\u0022:\u0022<GUID>\u0022}","ActivityId":"<GUID>"}

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

Проблему можно устранить следующим способом.

Убедитесь, что учетные данные базы данных действительны, в средстве, например sqlcmd или SQL Server Management Studio (SSMS).
Отмена связи и повторное связывание подключенной базы данных.

Если ошибка по-прежнему возникает, убедитесь, что вы выбрали разрешить службам и ресурсам Azure доступ к этому серверу для исключений на сетевой странице ресурса Базы данных Azure. Этот параметр настраивает брандмауэр, чтобы разрешить подключения из IP-адресов, выделенных любой службе Или ресурсу Azure, включая подключения из подписок других клиентов.

Конечная точка REST: ошибка HTTP 404 "Не найдена"

Если запрошенный URL-адрес указывает на маршрут, который не связан с какой-либо сущностью, возвращается ошибка HTTP 404. По умолчанию имя сущности также является именем маршрута. Например, если вы настроите пример сущности Todo в файле конфигурации следующим образом:

"Todo": {
      "source": "dbo.todos",
      "...": "..."
    }

Todo Затем сущность становится доступной по следующему маршруту:

/<rest-route>/Todo

Если указать свойство rest.path в конфигурации сущности на todo, как показано в следующем примере:

"Todo": {
    "source": "dbo.todos",
    "rest": {
      "path": "todo"
    },
    "...": "..."
  }

Затем URL-маршрут для сущности Todo — это todo, с использованием всех строчных символов, которые точно соответствуют значению, заданному в конфигурации среды выполнения.

/<rest-route>/todo

Конечная точка GraphQL: ошибка HTTP 400 "Недопустимый запрос"

Запрос GraphQL приводит к ошибке HTTP 400 "Недопустимый запрос" каждый раз при неправильном построении запроса GraphQL. Это может быть связано с отсутствующим полем сущности или с неверно написанным именем сущности. Конструктор API данных возвращает описательную ошибку и сведения об ошибке в полезных данных ответа.

При отправке запроса в конечную точку GET GraphQL в теле ответа будет указана ошибка: "Либо параметр запроса, либо идентификатор параметра должен быть задан". Обязательно отправляйте запросы GraphQL с помощью HTTP POST.

Конечная точка GraphQL: ошибка HTTP 404 "Не найдена"

Убедитесь, что запрос GraphQL отправляется в настроенную конечную точку GraphQL с помощью метода HTTP POST . По умолчанию маршрут конечной точки GraphQL имеет значение /graphql.

Конечная точка GraphQL: "Запрос типа объекта должен по крайней мере определить одно поле, чтобы быть допустимым" ошибка

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

Запрос типа объекта должен по крайней мере определить одно поле, чтобы быть допустимым.

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

Действие read определяется по крайней мере для одной сущности с поддержкой GraphQL. GraphQL включен для сущностей по умолчанию, поэтому убедитесь, что вы не применяете эту меру к сущности, настроенной с {"graphql": false}.
Если вы предоставляете только хранимые процедуры, определите { "graphql": { "operation": query" } } по крайней мере одну сущность хранимой процедуры, которая переопределяет тип mutationоперации GraphQL по умолчанию.

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

Конечная точка GraphQL: интроспекция не работает с GraphQL эндпоинтом.

Средства, поддерживающие GraphQL, обычно используют инспекцию схемы GraphQL, не требуя дополнительной настройки. Убедитесь, что свойство конфигурации среды выполнения allow-introspection установлено в true в разделе конфигурации runtime.graphql. Например:

"runtime": {
    "...": "...",
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "..."
}

Конечная точка GraphQL: "Операция изменения <operation_name> была успешной, но текущий пользователь не авторизован для просмотра ответа из-за отсутствия разрешений на чтение" ошибки

Чтобы операция мутации GraphQL получила допустимый ответ, разрешения на чтение должны быть настроены в дополнение к соответствующему типу операции мутации — созданию, обновлению и удалению. Как указывается в ошибке, операция мутации (create/update/delete) была успешно выполнена на уровне базы данных, но отсутствие разрешения на чтение привело к тому, что Data API Builder возвращает сообщение об ошибке. Поэтому обязательно настройте разрешения на чтение в роли "Анонимный" или в роли, с которой вы хотите выполнить операцию мутации.

Общая ошибка: ошибка HTTP 500, возвращаемая запросами

Ошибки HTTP 500 указывают на то, что построитель API данных не может правильно работать в серверной базе данных. Убедитесь, что выполняются следующие условия:

Построитель API данных по-прежнему может подключаться к настроенной базе данных.
Объекты базы данных, используемые конструктором API данных, по-прежнему доступны.

Чтобы конструктор API данных возвращал определенные ошибки базы данных в ответах, установите значение свойства конфигурации runtime.host.mode в development:

"runtime": {
    [...]
    "host": {
        "mode": "development",
        [...]
    }
}

По умолчанию построитель API данных выполняется с runtime.host.mode, установленным на production. В production режиме построитель Data API не возвращает подробные сообщения об ошибках в полезных данных ответа.

В режимах development и production конструктор API данных записывает подробные ошибки в консоль, чтобы помочь в устранении неполадок.

Общие ошибки из-за неавторизованных и несанкционированных запросов

Ошибка HTTP 401 "Несанкционированная"

Ошибки HTTP 401 возникают, когда доступ к конечной точке и сущности требует проверки подлинности, и запрашивающий не предоставляет допустимые метаданные проверки подлинности в запросе.

При настройке Data API builder для использования аутентификации через Microsoft Entra ID ваши запросы будут приводить к ошибкам HTTP 401, если предоставленный токен доступа недействителен. Маркер доступа может быть недействительным по многим причинам. Вот некоторые из них:

Срок действия маркера доступа истек.
Маркер доступа не предназначен для API построителя данных (неправильная аудитория маркера доступа).
Маркер доступа не создан ожидаемым удостоверяющим центром (недействительным издателем маркера доступа).

Чтобы устранить эту ошибку, обязательно выполните следующие условия:

Вы создаете маркер доступа с помощью issuer значения, определенного в authentication разделе конфигурации среды выполнения.
Ваш токен доступа создается для значения audience, определенного в разделе authentication конфигурации среды выполнения.

Ниже приведен пример конфигурации:

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "00001111-aaaa-2222-bbbb-3333cccc4444"
    }
}

Необходимо создать допустимый токен для определенной аудитории. При использовании Azure CLI можно получить маркер доступа, указав аудиторию в параметре resource :

az account get-access-token --resource "00001111-aaaa-2222-bbbb-3333cccc4444"

Ошибка HTTP 403 "Запрещено"

Если вы отправляете прошедший проверку подлинности запрос с помощью интеграции Статические веб-приложения или идентификатора Microsoft Entra, может появиться ошибка HTTP 403 "Запрещено". Эта ошибка означает, что вы пытаетесь использовать роль, которая не существует в файле конфигурации.

Эта ошибка возникает в следующих случаях:

Не укажите заголовок HTTP, указывающий X-MS-API-ROLE имя роли.

Так как запросы, прошедшие проверку подлинности, выполняются в контексте системной роли authenticated по умолчанию, этот сценарий применяется только при использовании не системной роли (а не authenticatedanonymous).
Роль, которую вы определяете в заголовке X-MS-API-ROLE, не настроена в файле конфигурации времени выполнения Data API builder.
Роль, определяемая в заголовке X-MS-API-ROLE, не соответствует роли в вашем токене доступа.

Например, в следующем файле конфигурации среды выполнения определяется роль role1, поэтому необходимо указать заголовок HTTP X-MS-API-ROLE со значением role1.

Примечание.

Учитывается чувствительность к регистру при сопоставлении имен ролей.

"Todo": {
    "role": "role1",
    "actions": [ "*" ]
}

Ссылки

Следующий шаг

Если проблема не устранена, предоставьте отзыв или сообщите о ней в разделе обсуждений Data API Builder.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-17