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

Artykuł
12/31/2024

W portalach można używać dostępnych operacji interfejsu Web API w Power Pages. 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 witryny 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	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	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	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ą [i]. We wszystkich opcjach zapytań rozróżniana jest wielkość liter, jak pokazano w poniższym przykładzie:

Method	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, aby ograniczyć zwracane właściwości, jak pokazano w poniższym przykładzie:

Method	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, aby ustawić kryteria, 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 towarów za pomocą kwerendy systemowej $orderby. Użyj sufiksu asc lub desc, aby określić odpowiednio kolejność rosnącą lub malejącą. 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	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 zapytania systemowego $count o wartości true, aby uwzględnić liczbę encji spełniających kryteria filtrowania do 5 000.

Method	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	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	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`

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

Musisz użyć Microsoft.Dynamics.CRM.associatednavigationproperty jako atrybutu wyszukiwania podczas korzystania z opcji zapytania $expand.

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

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	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)"
        }
    }
]
}

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

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. Nazwę relacji między tabelami należy określić w składni kodu.

Method	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)`

Zapytania o rekordy przy użyciu FetchXml

Przekaż zapytanie FetchXml jako wartość ciągu zakodowaną w adresie URL do kolekcji zestawu jednostek przy użyciu parametru zapytania FetchXml.

Na przykład, aby pobrać dane z zestawu podmiotów konta, utwórz zapytanie FetchXml ustawiające parametr entity element name na account.

<fetch top='2'>
  <entity name='account'>
      <attribute name='name' />
  </entity>
</fetch>

Ciąg zakodowany w adresie URL dla poprzedniego zapytania to:

%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E

Method	URI
GET	`[Portal URI]/_api/accounts?fetchxml` Przykład: `https://contoso.powerappsportals.com/_api/accounts?fetchXml=%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E`

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)"
      }
    }
  ]
}

Następny krok

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

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

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

Zapytania o rekordy przy użyciu FetchXml

Następny krok

Zobacz też

Opinia

Dodatkowe zasoby

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

Zapytania o rekordy przy użyciu FetchXml

Następny krok

Zobacz też

Opinia

Dodatkowe zasoby