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

Составление HTTP-запросов и обработка ошибок для веб-API порталов.

  • Статья

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

Внимание

  • Для работы этой функции ваша версия портала должна быть 9.3.3.x или более поздней.

URL-адрес и управление версиями веб-API

Создайте URL-адрес веб-API, используя формат, указанный в следующей таблице.

Часть Описание:
Протокол https://
Базовый URL-адрес <URL-адрес портала>
Путь к веб-API _api
Resource Логическое имя таблицы, которую нужно использовать

Например, используйте этот формат при ссылке на обращение:

https://contoso.powerappsportals.com/_api/case

Все ресурсы веб-API будут следовать соответствующим разрешениям таблицы в контексте с веб-ролями.

Методы HTTP

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

Способ Использование
Получить Используется при извлечении данных из таблиц.
POST Используйте при создании записей.
PATCH Используется при обновлении таблиц или выполнении операций upsert.
DELETE Используйте при удалении записей или значений отдельных полей записей.
PUT Используйте в ограниченных ситуациях для обновления отдельных полей записей.

Заголовки HTTP

Веб-API поддерживает только JSON. Каждый HTTP-заголовок должен включать:

  • Значение заголовка Принятьapplication/json, даже если тело ответа не ожидается.
  • Если запрос включает данные JSON в теле запроса, вы должны включить заголовок Content-Type со значениемapplication/json.

Текущая версия OData — 4.0, но в будущих версиях могут появиться новые возможности. Используйте следующий синтаксис, чтобы убедиться в отсутствии двусмысленности в версии OData, которая будет применяться к вашему коду в будущем:

Синтаксис

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Пример: функция Wrapper AJAX для токена CSRF

	(function(webapi, $){
		function safeAjax(ajaxOptions) {
			var deferredAjax = $.Deferred();
	
			shell.getTokenDeferred().done(function (token) {
				// add headers for ajax
				if (!ajaxOptions.headers) {
					$.extend(ajaxOptions, {
						headers: {
							"__RequestVerificationToken": token
						}
					}); 
				} else {
					ajaxOptions.headers["__RequestVerificationToken"] = token;
				}
				$.ajax(ajaxOptions)
					.done(function(data, textStatus, jqXHR) {
						validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
					}).fail(deferredAjax.reject); //ajax
			}).fail(function () {
				deferredAjax.rejectWith(this, arguments); // on token failure, pass the token ajax and args
			});
	
			return deferredAjax.promise();	
		}
		webapi.safeAjax = safeAjax;
})(window.webapi = window.webapi || {}, jQuery)

Пример: получить данные таблицы

	webapi.safeAjax({
				type: "GET",
				url: "/_api/contacts?$select=firstname,lastname",
				contentType: "application/json",
				success: function (res) {
						console.log(res);
				}
	});

Пример: создание данных таблицы

	webapi.safeAjax({
		type: "POST",
		url: "/_api/accounts",
		contentType: "application/json",
		data: JSON.stringify({
			"name": "Sample Account"
		}),
		success: function (res, status, xhr) {
			console.log("entityID: "+ xhr.getResponseHeader("entityid"))
		}
	});

Пример: обновление данных таблицы

		webapi.safeAjax({
		type: "PATCH",
		url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
		contentType: "application/json",
		data: JSON.stringify({
			"name": "Sample Account - Updated"
		}),
		success: function (res) {
			console.log(res);
		}
	});

Пример: удаление данных таблицы

		webapi.safeAjax({
		type: "DELETE",
		url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
		contentType: "application/json",
		success: function (res) {
			console.log(res);
		}
	});

Определение кодов состояния

Каждый ответ HTTP-запроса включает в себя код состояния. Коды состояния, возвращаемые веб-API порталов, включают следующее:

Код Description Type
200 OK Ожидайте этот ответ, когда ваша операция вернет данные в теле ответа. Удачное завершение
204 Нет контента Ожидайте этот ответ, когда ваша операция выполнена успешно, но не возвращает данные в теле ответа. Удачное завершение
403 Запрещено Ожидайте этот ответ для следующих типов ошибок:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Ошибка клиента
401 Не авторизовано Ожидайте этот ответ для следующих типов ошибок:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Ошибка клиента
413 Полезные данные слишком велики Ожидайте этот ответ, когда длина запроса слишком велика. Ошибка клиента
400 BadRequest Ожидайте этот ответ, когда аргумент неверен.
InvalidAttribute		 Ошибка клиента
404 Не найдено Ожидайте этот ответ, когда ресурс не существует.
Таблица не отображается для веб-API.		 Ошибка клиента
405 Метод не разрешен Эта ошибка возникает для неправильных комбинаций методов и ресурсов. Например, вы не можете использовать DELETE или PATCH для коллекции таблиц. Эта ситуация может возникнуть для следующих типов ошибок:
  • InvalidOperation
  • NotSupported
 Ошибка клиента
501 Не реализовано Ожидайте этот ответ, когда какая-то запрошенная операция не реализована. Ошибка сервера
503 Сервис недоступен Ожидайте этот ответ, когда служба веб-API недоступна. Ошибка сервера

Разбор ошибок из ответа

Рассмотрим следующий пример ответа HTTP, который все еще включает внутреннюю ошибку:

{
  "error":{
    "code": "This code is not related to the http status code and is frequently empty",
    "message": "A message describing the error",
    "cdscode": "Dataverse error code",
    "innererror": {
        "code": "800xxxx",
        "message": "A message describing the error. This is frequently the same as the outer message.."
      }
    }
  }

Коды ошибок

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

Код ошибки Имя ошибки Сообщение об ошибке
900400FF NoAttributesForTableCreate Нет атрибутов для действия создания таблицы.
90040100 InvalidAttribute Невозможно найти атрибут {0} для таблицы {1}.
90040101 AttributePermissionIsMissing Атрибут {0} в таблице {1} не включен для веб-API.
90040102 TablePermissionWriteIsMissingDuringUpdate У вас нет разрешения на обновление сущности {0}.
90040103 TablePermissionCreateIsMissing У вас нет разрешения на создание сущности {0}.
90040104 TablePermissionDeleteIsMissing У вас нет разрешения на удаление сущности {0).
90040105 TablePermissionAppendIsMissngDuringAssociationChange У вас нет разрешения на связь или отмену связи таблицы {0} с {1}.
90040106 TablePermissionAppendToIsMissingDuringAssociationChange У вас нет разрешения на связь или отмену связи таблицы {1} с {0}
90040107 HttpAntiForgeryException Токен cookie для защиты от подделки и токен поля формы не совпадают.
90040109 MissingPortalSessionCookie Недопустимый токен сеанса был передан в вызывающий метод.
9004010C ResourceDoesNotExists Ресурс не найден для сегмента "{0}".
9004010D CDSError Возникла ошибка CDS.

Ответ для необработанных ошибок с кодом состояния HTTP 500 вернет ошибку — "Произошла непредвиденная ошибка при обработке запроса".

См. также