Udostępnij za pośrednictwem

Tworzenie żądań HTTP i obsługa błędów dla interfejsu API sieci Web portali

  • Artykuł

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:
  • AccessDenied
  • AttributePermissionIsMissing
  • TablePermissionWriteIsMissingDuringUpdate
  • TablePermissionCreateIsMissing
  • TablePermissionDeleteIsMissing
  • TablePermissionAppendIsMissngDuringAssociationChange
  • TablePermissionAppendToIsMissingDuringAssociateChange
 Błąd klienta
401 Brak autoryzacji Spodziewaj się tej odpowiedzi na następujące typy błędów:
  • MissingPortalRequestVerificationToken
  • MissingPortalSessionCookie
 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:
  • InvalidOperation
  • NotSupported
 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).