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

Artykuł
03/15/2023

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.

W portalach można używać dostępnych operacji interfejsu Web API. Operacje interfejsu API sieci Web składają się z żądań i odpowiedzi HTTP. Ten artykuł zawiera przykładowe operacje odczytu, metody, identyfikator URI i przykładowy kod JSON, których można użyć w żądaniu HTTP.

Wymagania wstępne

Wersja portalu musi być 9.4.1.x lub wyższa.
Włącz tabelę i pole dla operacji interfejsu API sieci Web. Więcej informacji: Ustawienia witryny dla internetowego interfejsu API
Internetowy interfejs API portali uzyskuje dostęp do rekordów tabel i postępuje zgodnie z uprawnieniami do tabel przyznanymi użytkownikom za pośrednictwem skojarzonych ról internetowych. Upewnij się, że skonfigurowano poprawne uprawnienia do tabeli. Więcej informacji: Tworzenie ról internetowych

Uwaga

Odwołując się do tabel Dataverse za pomocą internetowego interfejsu API portali, musisz użyć EntitySetName, na przykład, aby uzyskać dostęp do tabeli konto, składnia kodu będzie używała nazwy EntitySetName z kont.

Zapytanie o rekordy

Poniższy przykład wysyła kwerendy do rekordów kont:

Operacja	Method	Identyfikator URI
Pobierz rekordy tabeli	GET	`[Portal URI]/_api/accounts` Przykład: `https://contoso.powerappsportals.com/_api/accounts`

Przykładowa odpowiedź

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

Użyj kwerendy systemowej $select i $top, aby zwrócić właściwość nazwa dla pierwszych trzech kont:

Operacja	Method	Identyfikator URI
Pobieranie pierwszych trzech rekordów encji	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Pobierz konto przy użyciu identyfikatora konta:

Operacja	Method	Identyfikator URI
Pobieranie określonej właściwości rekordu	GET	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` Przykład: `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

Przykładowa odpowiedź

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

Stosowanie opcji zapytań systemowych

Każda z opcji kwerendy systemowej dołączonej do adresu URL zestawu encji jest dodawana przy użyciu składni ciągów zapytania. Pierwszy jest dołączany po [?], a następujące opcje zapytania są oddzielane za pomocą [&]. We wszystkich opcjach zapytań rozróżniana jest wielkość liter, jak pokazano w poniższym przykładzie:

Method	Identyfikator URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3`

Poproś o określone właściwości

Użyj opcji zapytania systemowego $select w celu ograniczenia zwracanych właściwości, jak pokazano w poniższym przykładzie:

Method	Identyfikator URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Ważne

To jest najlepsza praktyka wydajności. Jeśli nie określono właściwości, a wartość ustawienia witryny Webapi/<table name>/fields została skonfigurowana na *, wszystkie właściwości zostaną zwrócone za pomocą $select. Jeśli nie określono żadnych właściwości, zostanie zwrócony błąd.

Filtruj wyniki

Użyj zapytania systemowego $filter w celu ustawienia kryteriów, dla których wiersze będą zwracane.

Standardowe operatory filtrów

Internetowy interfejs API obsługuje standardowe operatory filtrów OData wymienione w poniższej tabeli:

Operator	Opis	Przykład
Operatory porównania
eq	Równa się	$filter=100000 eq przychodów
ne	Nie równa się	$filter=100000 ne przychodów
gt	Większe niż	$filter=100000 gt przychodów
ge	Większe niż lub równe	$filter=100000 ge przychodów
lt	Mniejsze niż	$filter=100000 it przychodów
le	Mniejsze niż lub równe	$filter=100000 le przychodów
Operatory logiczne
and	Zestaw and	$filter=przychód lt 100000 i dochód gt 2000
or	Logiczne or	$filter=contains(name,'(sample)') or contains(name,'test')
not	Logiczna negacja	$filter=not contains(name,'sample')
Grupowanie operatorów
( )	Grupowanie pierwszeństwa	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Standardowe funkcje zapytań

Internetowy interfejs API obsługuje następujące standardowe funkcje kwerendy ciągu OData:

Funkcja	Przykład
zawiera	$filter=contains(name,'(sample)')
kończy się na	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

Funkcje zapytań Dataverse

Interfejs API sieci Web obsługuje funkcje zapytań Dataverse w celu filtrowania wyników. Aby uzyskać więcej informacji, zobacz temat Odwołanie do funkcji zapytania internetowego interfejsu API.

Wyniki kolejności

Określ kolejność zwracania elementów za pomocą opcji zapytania systemowego $orderby . Użyj sufiksu asc lub desc w celu określenia odpowiednio kolejności rosnącej lub malejącej. Wartość domyślna to rosnąco, jeśli sufiks nie zostanie zastosowany. Poniższy przykład pokazuje pobieranie nazwy i właściwości przychodów kont uporządkowanych według rosnących przychodów i malejących nazw.

Method	Identyfikator URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000`

Wyniki agregacji i grupowania

Korzystając z $apply , można dynamicznie agregować i grupować dane, jak widać w poniższych przykładach:

Scenariusze	Przykład
Lista unikalnych statusów w zapytaniu	accounts?$apply=groupby((statuscode))
Łączna suma wartości szacunkowej	opportunities?$apply=aggregate(estimatedvalue with sum as total)
Średnia wielkość transakcji na podstawie szacunkowej wartości i statusu	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Suma szacowanej wartości na podstawie statusu	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Łączne przychody z możliwości według nazwy konta	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Nazwy głównych kontaktów dla kont w „WA”	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data i godzina ostatniego utworzenia nagrania	accounts?$apply=aggregate(createdon with max as lastCreate)
Data i godzina pierwszego utworzenia nagrania	accounts?$apply=aggregate(createdon with min as firstCreate)

Pobieranie liczby wierszy

Użyj opcji zapytania systemowego $count o wartości true, aby uwzględnić liczbę encji spełniających kryteria filtrowania do 5000.

Method	Identyfikator URI
GET	`[Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true`

Przykładowa odpowiedź

{
"@odata.count": 10,
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

Jeśli nie chcesz zwracać żadnych danych z wyjątkiem licznika, możesz zastosować $count do dowolnej kolekcji, aby uzyskać tylko wartość.

Method	Identyfikator URI
GET	`[Portal URI/_api/accounts/$count` Przykład: `https://contoso.powerappsportals.com/_api/accounts/$count`

Przykładowa odpowiedź

3

Porównanie kolumn

Poniższy przykład pokazuje, jak porównywać kolumny przy użyciu internetowego interfejsu API:

Method	Identyfikator URI
GET	`[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname` Przykład: `https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname`

Pobieranie powiązanych rekordów tabeli za pomocą kwerendy

Użyj opcji zapytania systemowego $expand we właściwościach nawigacji, aby kontrolować, jakie dane z powiązanych encji są zwracane.

Wyszukaj powiązaną właściwość nawigacji

W przypadku korzystania z opcji zapytania $expand jako atrybutu wyszukiwania należy użyć Microsoft.Dynamics.CRM.associatednavigationproperty.

Aby określić Microsoft.Dynamics.CRM.associatednavigationproperty atrybutu, możesz wykonać następujące żądanie http GET dla kolumny przy użyciu następującej konwencji nazewnictwa: _name_value.

W poniższym przykładzie możemy określić powiązaną właściwość nawigacji kolumny Kontakt podstawowy tabeli Konto przez określenie nazwy kolumny primarycontactid przez sformatowanie nazwy w żądaniu: _primarycontactid_value.

Method	Identyfikator URI
GET	`[Portal URI]/_api/accounts?$select=_primarycontactid_value` Przykład `https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value`

Przykładowa odpowiedź

{
"value": [
    {
        "@odata.etag": "W/\"2465216\"",
        "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
        "_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
        "accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
    }
]
}

Z odpowiedzi wynika, że skojarzona właściwość nawigacji to primarycontactid. Skojarzona właściwość nawigacji może być nazwą logiczną lub nazwą schematu kolumny wyszukiwania w zależności od sposobu tworzenia tabeli.

Aby uzyskać więcej informacji, zobacz temat Pobieranie danych dotyczących właściwości wyszukiwania.

Pobieranie powiązanych rekordów tabeli przez rozwinięcie jednowartościowych właściwości nawigacji

Poniższy przykład pokazuje, jak pobrać kontakt dla wszystkich rekordów konta. W przypadku powiązanych rekordów kontaktów pobieramy tylko identyfikator contactid i fullname.

Method	Identyfikator URI
GET	`[Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)`

Przykładowa odpowiedź

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Yvonne McKay (sample)"
        }
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Susanna Stubberod (sample)"
        }
    }
]
}

Pobierz powiązane tabele, rozwijając właściwości nawigacji o wartościach kolekcji

Jeśli rozwiniesz parametry nawigacji o wartościach kolekcji, aby pobrać powiązane tabele dla zestawów jednostek, zostanie zwrócony tylko jeden poziom głębokości, jeśli istnieją dane. W przeciwnym razie kolekcja zwróci pustą tablicę.

Method	Identyfikator URI
GET	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)`

Pobierz powiązane tabele, rozwijając właściwości nawigacji o wartości pojedynczej i kolekcji

Poniższy przykład ilustruje sposób rozwijania powiązanych encji dla zestawów encji przy użyciu zarówno właściwości nawigacji pojedynczej, jak i o wartości kolekcji. W składni kodu należy podać nazwę relacji między tabelami.

Method	Identyfikator URI
GET	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)` Przykład: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)`

Następny krok

Portale zapisują, aktualizują i usuwają operacje za pomocą Web API

Zobacz też

Opis internetowego interfejsu API portali
Samouczek: Używanie internetowego interfejsu API portali
Konfiguruj uprawnienia kolumn

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).

Udostępnij za pośrednictwem

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

Wymagania wstępne

Zapytanie o rekordy

Stosowanie opcji zapytań systemowych

Poproś o określone właściwości

Filtruj wyniki

Standardowe operatory filtrów

Standardowe funkcje zapytań

Funkcje zapytań Dataverse

Wyniki kolejności

Wyniki agregacji i grupowania

Pobieranie liczby wierszy

Porównanie kolumn

Pobieranie powiązanych rekordów tabeli za pomocą kwerendy

Wyszukaj powiązaną właściwość nawigacji

Pobieranie powiązanych rekordów tabeli przez rozwinięcie jednowartościowych właściwości nawigacji

Pobierz powiązane tabele, rozwijając właściwości nawigacji o wartościach kolekcji

Pobierz powiązane tabele, rozwijając właściwości nawigacji o wartości pojedynczej i kolekcji

Następny krok

Zobacz też

Dodatkowe zasoby