Tworzenie żądań HTTP i obsługa błędów dla interfejsu API sieci Web portali
Uwaga
12 października 2022 r. funkcja Portale usługi Power Apps została przekształcona w usługę Power Pages. Więcej informacji: Usługa Microsoft Power Pages jest teraz ogólnie dostępna (blog)
Wkrótce zmigrujemy i scalimy dokumentację funkcji Portale usługi Power Apps z dokumentacją usługi Power Pages.
Interakcja z interfejsem API sieci Web obejmuje tworzenie żądań HTTP z wymaganymi nagłówkami i obsługę odpowiedzi HTTP, w tym wszelkich błędów.
Ważne
- Aby ta funkcja działała, trzeba mieć wersję portali 9.3.3.x lub nowszą.
Adres URL i przechowywanie wersji interfejsu API sieci Web
Utwórz adres URL interfejsu API sieci Web, stosując format podany w poniższej tabeli.
| Element | opis |
|---|---|
| Protokół | https:// |
| Podstawowy adres URL | <portal URL> |
| Ścieżka interfejsu API sieci Web | _api |
| Zasób | Nazwa logiczna tabeli, której chcesz użyć |
Na przykład ten format należy stosować w przypadku odwoływania się do sprawy:
https://contoso.powerappsportals.com/_api/case
Wszystkie zasoby interfejsu API sieci Web postępują zgodnie z odpowiednimi uprawnieniami tabeli portalu w kontekście ról sieci Web.
Metody HTTP
Żądania HTTP mogą używać różnych rodzajów metod. Interfejs API sieci Web Portal obsługuje jednak tylko metody wymienione w poniższej tabeli:
| Method | Sposób użycia |
|---|---|
| Get | Używany podczas pobierania danych z tabel. |
| Post | Używaj podczas tworzenia rekordów. |
| Poprawka | Danych należy używać podczas aktualizowania tabel lub wykonywania operacji ups uaktualnień. |
| Delete | Należy użyć podczas usuwania rekordów lub poszczególnych wartości pól rekordów. |
| Put | Używaj w ograniczonych sytuacjach do aktualizacji indywidualnych pól rekordów. |
Nagłówki HTTP
Interfejs API sieci Web obsługuje tylko notację JSON. Każdy nagłówek HTTP musi zawierać następujące:
- Wartość Potwierdź nagłówka elementu application/json nawet wtedy, gdy nie jest oczekiwana treść odpowiedzi.
- Jeśli żądanie zawiera dane JSON w treści żądania, należy umieścić w nagłówku typu-zawartość z wartością
application/json.
Bieżąca wersja OData to 4,0, ale przyszłe wersje mogą pozwolić na nowe możliwości. Użyj następującej składni, aby upewnić się, że nie ma dwuznaczności co do wersji OData, która zostanie zastosowana do kodu w przyszłości:
Składnia
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Przykład: funkcja AJAX z otoką dla tokenu 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)
Przykład: Pobieranie danych tabeli
webapi.safeAjax({
type: "GET",
url: "/_api/contacts?$select=firstname,lastname",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Przykład: Tworzenie danych tabeli
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"))
}
});
Przykład: Aktualizacja danych tabeli
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);
}
});
Przykład: Usuwanie danych tabeli
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});
Zidentyfikuj kody stanu
Każda odpowiedź HTTP z żądaniem zawiera kod stanu. Kody stanu zwracane przez interfejs API sieci Web portali obejmują następujące elementy:
| Kod | Description | Type |
|---|---|---|
| 200 OK | Oczekiwanie tej odpowiedzi w przypadku, gdy w operacji będą zwracane dane w treści odpowiedzi. | Powodzenie |
| 204 Brak zawartości | Spodziewaj się tej odpowiedzi, gdy operacja zakończy się pomyślnie, ale nie zwraca danych w treści odpowiedzi. | Powodzenie |
| 403 Zabronione | Spodziewaj się tej odpowiedzi na następujące typy błędów:
|
Błąd klienta |
| 401 Brak autoryzacji | Spodziewaj się tej odpowiedzi na następujące typy błędów:
|
Błąd klienta |
| 413 Zbyt duży ładunek | Spodziewaj się tej odpowiedzi, kiedy długość żądania jest zbyt duża. | Błąd klienta |
| 400 BadRequest | Spodziewaj się tej odpowiedzi, jeśli argument jest nieprawidłowy. InvalidAttribute |
Błąd klienta |
| 404 Nie znaleziono | Spodziewaj się tej odpowiedzi, jeśli dany zasób nie istnieje. Tabela nie jest widoczne dla interfejsu API sieci Web. |
Błąd klienta |
| 405 Metoda niedozwolona | Ten błąd występuje w przypadku nieprawidłowej kombinacji metody i zasobu. Nie można na przykład użyć USUŃ lub POPRAWKA w zbiorze tabel. Taka sytuacja może wystąpić w przypadku następujących typów błędów:
|
Błąd klienta |
| 501 Nie zaimplementowano | Spodziewaj się tej odpowiedzi w przypadku, gdy nie zaimplementowano jakiejś żądanej operacji. | Błąd serwera |
| 503 Usługa niedostępna | Spodziewaj się tej odpowiedzi w przypadku, gdy usługa API sieci Web jest niedostępna. | Błąd serwera |
Analiza błędów z odpowiedzi
Rozważmy następujący przykład odpowiedzi HTTP, który nadal zawiera błąd wewnętrzny:
{
"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.."
}
}
}
Kody błędów
Kody błędów są wyświetlane w formacie szesnastkowym we wszystkich obdługiwanych scenariuszach. W poniższej tabeli podano wszystkie kody błędów wraz z odpowiednimi nazwami i komunikatami.
| Kod błędu | Błąd nazwy | Komunikat o błędzie |
|---|---|---|
| 900400FF | NoAttributesForTableCreate | Brak atrybutów dla akcji Utwórz tabelę. |
| 90040100 | InvalidAttribute | Nie można odnaleźć atrybutu {0} dla tabeli {1}. |
| 90040101 | AttributePermissionIsMissing | Atrybut {0} w tabeli {1} nie jest włączony do użycia w internetowym interfejsie API. |
| 90040102 | TablePermissionWriteIsMissingDuringUpdate | Nie masz uprawnienia umożliwiającego zaktualizowanie encji {0}. |
| 90040103 | TablePermissionCreateIsMissing | Nie masz uprawnienia umożliwiającego utworzenie encji {0}. |
| 90040104 | TablePermissionDeleteIsMissing | Nie masz uprawnienia umożliwiającego usunięcie {0) encji. |
| 90040105 | TablePermissionAppendIsMissngDuringAssociationChange | Nie masz uprawnienia umożliwiającego skojarzenie tej tabeli {0} z elementem {1} lub usunięcie tego skojarzenia. |
| 90040106 | TablePermissionAppendToIsMissingDuringAssociationChange | Nie masz uprawnienia umożliwiającego skojarzenie tej tabeli {1} z elementem {0} lub usunięcie tego skojarzenia. |
| 90040107 | HttpAntiForgeryException | Nie pasuje do tokenu pliku cookie przeciwko fałszerstwu i tokenu pola formularza. |
| 90040109 | MissingPortalSessionCookie | Do metody rzucania przekazano nieprawidłowy token sesji. |
| 9004010C | ResourceDoesNotExists | Nie znaleziono zasobu dla segmentu „{0}”. |
| 9004010D | CDSError | Wystąpił błąd usługi CDS. |
Odpowiedź na nieobsłużone błędy z kodem stanu HTTP 500 spowoduje zwrócenie błędu „Wystąpił nieoczekiwany błąd podczas przetwarzania żądania”.
Zobacz też
Opis internetowego interfejsu API portali
Portale zapisują, aktualizują i usuwają operacje za pomocą Web API
Portale odczytuje operacje przy użyciu internetowego interfejsu API
Uwaga
Czy możesz poinformować nas o preferencjach dotyczących języka dokumentacji? Wypełnij krótką ankietę. (zauważ, że ta ankieta jest po angielsku)
Ankieta zajmie około siedmiu minut. Nie są zbierane żadne dane osobowe (oświadczenie o ochronie prywatności).
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla