Opis internetowego interfejsu API portali

Web API portali umożliwia bogatsze doświadczenie użytkownika na stronach witryn Power Pages. Za pomocą internetowego interfejsu API można wykonywać operacje tworzenia, odczytywania, aktualizowania i usuwania we wszystkich tabelach Microsoft Dataverse ze stron witryn. Można na przykład utworzyć nowe konto lub zaktualizować kontakt bez użycia formularza lub formularza wieloetapowego przy użyciu internetowego interfejsu API portali.

Interfejs Web API używa trasy /_api (na przykład https://yoursite.powerappsportals.com/_api/accounts) i jest zgodny z wzorcem RESTful podobnym do interfejsu Web API usługi Dataverse.

Ważne

  • Interfejs Web API portali jest przeznaczony do tworzenia zaawansowanego interfejsu użytkownika na stronach portalu. Nie jest zoptymalizowany pod kątem integracji usług lub aplikacji innych firm. Integrowanie z innymi witrynami Power Pages przy użyciu internetowego interfejsu API portali nie jest obsługiwane.
  • Operacje internetowego interfejsu API portali ograniczone są do tabel powiązanych z danymi — na przykład konta, kontakty lub tabele niestandardowe. Konfigurowanie danych tabeli metadanych lub tabeli konfiguracji portalu — na przykład konfigurowanie tabel portali, takich jak adx_contentsnippet, adx_entityform lub adx_entitylist — nie jest obsługiwane przy użyciu internetowego interfejsu API portali. Aby uzyskać pełną listę, zobacz nieobsługiwane tabele konfiguracji w dalszej części tego artykułu.
  • Internetowy interfejs API portali korzysta z buforowania po stronie serwera, więc kolejne wywołania internetowego interfejsu API są szybsze niż początkowe wywołania. Należy zauważyć, że wyczyszczenie pamięci podręcznej serwera portalu powoduje tymczasowe obniżenie wydajności.
  • Operacje interfejsu Portals Web API wymagają licencji Power Pages. Na przykład wywołania interfejsu API sieci Web wprowadzone przez użytkowników anonimowych są liczone w celu osiągnięcia wydajności anonimowego użytkownika. Wywołania interfejsu API sieci Web wprowadzone przez użytkowników uwierzytelnionych (wewnętrznych lub zewnętrznych) nie są liczone w celu wyświetlenia stron, ale wymagają odpowiednich licencji uprawniających do korzystania z dyspozycyjności przez uwierzytelnionych użytkowników. Aby uzyskać więcej informacji, zobacz często zadawane pytania dotyczące licencjonowania Power Pages.
  • Wywoływanie akcji i funkcji przy użyciu internetowego interfejsu API portali nie jest obsługiwane.

Operacje interfejsu API sieci Web

Internetowy interfejs API portali oferuje podzestaw możliwości operacji Dataverse, które można wykonać za pomocą interfejsu API usługi Dataverse. Format API jest jak najbardziej zbliżony do oryginału, aby skrócić czas potrzebny na opanowanie go.

Uwaga

W operacjach internetowego interfejsu API jest uwzględniana wielkość liter.

Operacje Web API dostępne w usłudze Power Pages

Ustawienia witryny dotyczące internetowego interfejsu API

Ważne

Obsługa wartości symbolu wieloznacznego (*) w ustawieniu witryny Webapi/<table-name>/fields jest przestarzała.

Zastąp * listą kolumn rozdzielonych przecinkami wymaganych przez witrynę. Żądania interfejsu Web API usługi Power Pages dla tabel skonfigurowanych z * kończą się niepowodzeniem, dopóki nie skonfigurujesz jawnych nazw kolumn.

Aby włączyć interfejs API sieci Web portali dla witryny, skonfiguruj ustawienia witryny dla każdej tabeli, którą chcesz uwidocznić. Kolumny dostępne dla internetowego interfejsu API można zdefiniować, wymieniając je w ustawieniu witryny, przy użyciu widoku systemowego Dataverse lub łącząc obie metody.

Uwaga

Należy użyć nazwy logicznej tabeli dla tych ustawień (na przykład klienta).

Nazwa ustawień witryny Opis
Webapi/<table-name>/enabled Włącza lub wyłącza interfejs Web API dla <table name>.
Domyślny:False
Prawidłowe wartości:True, False
Webapi/<table-name>/fields Definiuje rozdzielaną przecinkami listę nazw logicznych kolumn dostępnych za pośrednictwem internetowego interfejsu API. Na przykład name,accountnumber,telephone1. To ustawienie jest wymagane, chyba że Webapi/<table-name>/UseFieldsFromView ustawiono na wartość True, a skonfigurowany widok systemowy zawiera co najmniej jedną kwalifikującą się kolumnę. Wartość symbolu wieloznacznego (*) jest przestarzała.
Webapi/<table-name>/UseFieldsFromView Gdy jest ustawiona wartość True, tworzy kolumny z widoku systemowego Dataverse o nazwie Power Pages Web API Columns dostępne za pośrednictwem interfejsu API sieci Web. Domyślnie:False. Prawidłowe wartości:True, False. Jeśli Webapi/<table-name>/fields jest również skonfigurowane, kolumny z obu źródeł są łączone.
Webapi/error/innererror Włącza lub wyłącza InnerError.
Domyślny:False
Prawidłowe wartości:True, False

Na przykład w celu udostępnienia interfejsu API sieci Web dla tabeli Sprawa, w której uwierzytelnieni użytkownicy mogą wykonywać operacje tworzenia, aktualizowania i usuwania dla tej encji, ustawienia witryny przedstawiono w następującej tabeli.

Nazwa ustawień witryny Wartość ustawienia witryny
Webapi/incident/enabled prawda
Webapi/incident/fields attr1, attr2, attr3

Konfigurowanie kolumn Web API przy użyciu widoku systemowego

Korzystając z widoku systemu, twórcy mogą zarządzać kolumnami dostępnymi za pośrednictwem internetowego interfejsu API portalu bez utrzymywania listy rozdzielanej przecinkami w ustawieniu witryny.

  1. W Power Pages studio projektowym otwórz obszar roboczy Dane.
  2. Wybierz tabelę, wybierz kartę Widoki, a następnie utwórz lub edytuj publiczny widok systemowy.
  3. Nadaj widokowi nazwę Kolumny Web API usługi Power Pages.
  4. Dodaj kolumny potrzebne w witrynie do widoku, a następnie zapisz i opublikuj widok.
  5. W aplikacji Zarządzanie portalem utwórz Webapi/<table-name>/UseFieldsFromView ustawienie witryny dla witryny internetowej i ustaw jej wartość na True.
  6. Sprawdź, czy Webapi/<table-name>/enabled jest ustawione na wartość True.

Uwaga

  • Uwzględniane są tylko kolumny z tabeli podstawowej wyświetlanej w widoku. Kolumny z powiązanych tabel nie są uwzględniane. Kolumny używane tylko do filtrowania lub sortowania nie są uwzględniane, chyba że są one również wyświetlane w widoku.
  • W przypadku kolumn wyszukiwania użyj odpowiedniej właściwości wyszukiwania OData w żądaniach internetowego interfejsu API. Nazwa właściwości używa formatu _<column-logical-name>_value. Na przykład kolumna wyszukiwania primarycontactid jest zwracana jako _primarycontactid_value.
  • Zmiany w widoku systemowego mogą stać się dostępne dla interfejsu API sieci Web w ciągu pięciu minut.

Jeśli zarówno Webapi/<table-name>/fields, jak i Webapi/<table-name>/UseFieldsFromView są skonfigurowane, internetowy interfejs API łączy kolumny wymienione w Webapi/<table-name>/fields z uprawnionymi kolumnami z widoku systemowego Kolumny internetowego interfejsu API usługi Power Pages dla tej tabeli.

Ważne

  • Ustawienie Webapi/<table-name>/UseFieldsFromView witryny jest dostępne w witrynie Power Pages w wersji 9.8.8.x lub nowszej.
  • Obsługa wartości symbolu wieloznacznego (*) w Webapi/<table-name>/fields jest przestarzała. Użyj jawnych nazw kolumn, widoku systemowego Power Pages Web API Columns lub obu.

Zabezpieczenia za pomocą internetowego interfejsu API portalu

Zabezpieczenia oparte na rekordach można skonfigurować dla poszczególnych rekordów w portalach przy użyciu uprawnień tabeli. Interfejs API sieci Web portali uzyskuje dostęp do rekordów tabeli (encji) i postępuje zgodnie z uprawnieniami do tabeli nadawanych użytkownikom za pośrednictwem skojarzonej roli Internet.

Uprawnienia kolumn można skonfigurować w celu dalszego definiowania uprawnień do poszczególnych kolumn w tabeli podczas korzystania z internetowego interfejsu API portalu.

Uwierzytelnianie żądań internetowego interfejsu API portalu

Nie ma potrzeby dołączania kodu uwierzytelniającego, ponieważ sesja aplikacji zarządza uwierzytelnianiem i autoryzacją. Wszystkie wywołania Web API muszą zawierać token CSRF (Cross-Site Request Forgery).

Używanie elementu EntitySetName

W przypadku odwoływania się do tabel Usługi Dataverse przy użyciu internetowego interfejsu API portalu w kodzie użyj nazwy EntitySetName. Aby uzyskać dostęp do tabeli konto, na przykład składnia kodu używa nazwy EntitySetName kont; /_api/accounts().

Uwaga

Użyj logicznej nazwy tabeli dla ustawień witryny (na przykład account).

Aby określić EntitySetName określonych tabel, wykonaj następujące kroki:

  1. Przejdź do https://make.powerapps.com

  2. Wybierz kartę Dataverse z panelu bocznego i wybierz tabelę.

  3. Wybierz opcję ... (Polecenia), a następnie wybierz pozycję Zaawansowane, Narzędzia i Kopiuj nazwę zestawu encji, aby skopiować nazwę EntitySetName tabeli do schowka.

    Jak znaleźć właściwość EntitySetName tabeli w Dataverse.

Prawa i przepisy dotyczące prywatności

Wszystkie nagłówki żądań używają identyfikatora kontaktu do celów audytu. W przypadku użytkownika anonimowego wartość to null.

Jeśli włączone jest rejestrowanie inspekcji, użytkownik może zobaczyć wszystkie zdarzenia inspekcji w dzienniku inspekcji Office 365.

Zrzut ekranu dziennika audytu Office 365.

Więcej informacji:
Włączanie funkcji Rejestrowanie działań i korzystanie z niej
Eksportowanie, Konfigurowanie i wyświetlanie rekordów dziennika inspekcji

Nieobsługiwane tabele konfiguracji

Nie można użyć internetowego interfejsu API portalu dla następujących tabel konfiguracji:

adx_contentaccesslevel – poziom dostępu do zawartości

adx_contentsnippet – fragment zawartości

adx_entityform

adx_entityformmetadata

adx_entitylist

adx_entitypermission

adx_entitypermission_webrole

adx_externalidentity

adx_pagealert

adx_pagenotification – powiadomienie dotyczące strony

adx_pagetag – etykieta strony

adx_pagetag_webpage

adx_pagetemplate – szablon strony

adx_portallanguage – język portalu

adx_publishingstate – stan publikowania

adx_publishingstatetransitionrule – reguła przejścia stanu publikowania

adx_publishingstatetransitionrule_webrole

adx_redirect

adx_setting

adx_shortcut

adx_sitemarker – znaczniki witryn

adx_sitesetting – ustawienia strony

adx_urlhistory

adx_webfile

adx_webfilelog

adx_webform – formularz strony

adx_webformmetadata – metadane formularza strony

adx_webformsession

adx_webformstep

adx_weblink – link do strony

adx_weblinkset

adx_webnotificationentity

adx_webnotificationurl

adx_webpage

adx_webpage_tag – etykieta witryny

adx_webpageaccesscontrolrule – reguła kontroli dostępu do stron internetowych

adx_webpageaccesscontrolrule_webrole

adx_webpagehistory – historia strony internetowej

adx_webpagelog – dziennik strony

adx_webrole_systemuser

adx_website – witryna sieci web

adx_website_list

adx_website_sponsor

adx_websiteaccess – dostęp do witryn internetowych

adx_websiteaccess – dostęp do witryn internetowych, rola na stronie

adx_websitebinding

adx_websitelanguage – język witryny internetowej

adx_webtemplate – szablon strony

Limitations

Niestandardowe tabele działań dziedziczą kolumny podstawowe (takie jak subject, description, activityidi createdon) z activitypointer tabeli. W przypadku konfigurowania kolumn internetowego interfejsu API dla niestandardowej tabeli działań przy użyciu Webapi/<table-name>/fields, widoku systemu Power Pages Web API Columns lub $select, należy uwzględnić co najmniej jedną kolumnę zdefiniowaną bezpośrednio w tej tabeli, a nie tylko dziedziczone kolumny.

Jeśli skonfigurujesz tylko dziedziczone activitypointer kolumny, internetowy interfejs API nie będzie mógł wykryć wyboru kolumn specyficznych dla tabeli. W związku z tym żądanie jest traktowane jako symbol wieloznaczny (*) i zwraca następujący błąd, nawet jeśli jawnie konfigurujesz pola: Atrybut Wszystkie kolumny nie jest włączony dla Web API.

Zalecenie: Uwzględnij co najmniej jedną kolumnę zdefiniowaną bezpośrednio w niestandardowej tabeli działań, taką jak Komentarze portalu/adx_portalcomment, wraz ze wszystkimi dziedziczonymi kolumnami.

Znane problemy

Użytkownicy otrzymują błąd CDS, jeśli wywołają żądanie GET interfejsu API sieci Web dla tabel, które mają wiele poziomów jeden-do wielu lub wiele do wielu uprawnienia do tabeli, gdy zakresy Nadrzędne, Kontakt lub Konto dodają więcej warunków do zapytania.

Aby rozwiązać ten problem, użyj narzędzia FetchXML w zapytaniu OData.

Następny krok

Wykonywanie zapytań o dane przy użyciu interfejsu API sieci Web portali

  • Ostatnia aktualizacja o