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

2024-06-19

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

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

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

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

База компонента пути URL-адреса сопоставляется с конечной точкой REST или GraphQL построителя данных. Если база компонента пути 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.

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

При использовании построителя данных с функцией подключения к базе данных Статические веб-приложения в тексте ответа возникает сообщение об ошибке "Код состояния ответа не указывает на успех: 400 (недопустимый запрос)" в тексте ответа:

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

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

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

Убедитесь, что учетные данные базы данных действительны в средстве, например Azure Data Studio или 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. Это может быть связано с полем сущности, не имеющимся, или именем сущности с ошибкой. Построитель данных возвращает описательную ошибку и сведения об ошибке в полезных данных ответа.

При отправке запроса в 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: introspection не работает с конечной точкой GraphQL

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "b455fa3c-15fa-4864-8bcd-88fd83d686f3"
    }
}

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

az account get-access-token --resource "b455fa3c-15fa-4864-8bcd-88fd83d686f3"

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

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

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

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

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

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

Примечание.

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

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

Ссылки

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

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

Свяжитесь с нами для получения помощи

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