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

Створення запитів HTTP і обробка помилок для веб-API порталів

  • Стаття

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

Важливо

  • Для роботи цієї функції необхідно, щоб версія порталу була 9.3.3.x або вище.

URL-адреса API веб-служб та робота із версіями

Створіть URL-адресу API веб-служб, використовуючи формат у таблиці нижче.

Частина Опис
Протокол https://
Основна URL-адреса <URL-адреса порталу>
Шлях до API веб-служб _api
Ресурс Логічне ім'я таблиці, яку потрібно використати

Наприклад, для посилання на інцидент використовуйте наведений нижче формат.

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

Усі ресурси API веб-служб будуть дотримуватися відповідних дозволів таблиць у контексті веб-ролей.

Методи HTTP

HTTP-запити можуть використовувати різні види методів Однак API веб-служб порталів підтримує лише методи, наведені в цій таблиці:

Спосіб зв’язку Використання
Get Використовується для отримання даних із таблиць.
Після Використовуйте при створенні записів.
Patch Використовується для оновлення таблиць або операцій без додаткової інформації.
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

Приклад: функція 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 веб-служб порталів, наведено нижче.

Код Опис Ввести
200 OK Ця відповідь є очікуваною, якщо ваша операція повертатиме дані у тексті відповіді. Успіх
204 No Content Ця відповідь є очікуваною, якщо ваша операція успішно виконана, але не повертає даних у тексті відповіді. Успіх
403 Заборонено Ця відповідь надходить, якщо виникає помилка, що належить до одного з перелічених типів.
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Помилка клієнта
401 Не авторизовано Ця відповідь надходить, якщо виникає помилка, що належить до одного з перелічених типів.
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 Помилка клієнта
413 Payload Too Large Ця відповідь надходить, якщо довжина запиту завелика. Помилка клієнта
400 BadRequest Ця відповідь надходить, якщо аргумент є неприпустимим.
InvalidAttribute		 Помилка клієнта
404 Not Found Очікуйте цю відповідь, коли ресурс не існує.
Таблиця не доступна для Web API.		 Помилка клієнта
405 Method Not Allowed Ця помилка виникає, якщо використовується неприпустима комбінація методу та ресурсу. Наприклад, не можна використовувати DELETE або PATCH для колекцій таблиць. Така ситуація може виникати для перелічених нижче типів помилок.
  • InvalidOperation
  • NotSupported
 Помилка клієнта
501 Not Implemented Ця відповідь надходить, якщо якусь з операцій, згадану у запиті, не реалізовано. Помилка сервера
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 NoAttributesForEntityCreate Немає атрибутів для дії "Створити таблицю".
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 повертатиме помилку «Виникла непередбачувана помилка під час обробки запиту».

Див. також