Pertanyaan data menggunakan API Web portal

Anda boleh menggunakan operasi API Web tersedia dalam Power Pages. Operasi API Web terdiri daripada permintaan dan respons HTTP. Artikel ini menyediakan sampel operasi baca, kaedah, URI dan JSON sampel yang boleh anda gunakan dalam permintaan HTTP.

Prasyarat

  • Versi tapak web anda mestilah 9.4.1.x atau lebih tinggi.

  • Dayakan jadual dan medan untuk operasi API Web. Maklumat lanjut, Tetapan tapak untuk API Web

  • API Web portal mengakses jadual rekod mengikut keizinan jadual yang diberikan kepada pengguna melalui yang berkaitan peranan web. Pastikan anda mengkonfigurasi keizinan jadual yang betul. Maklumat lanjut: Cipta peranan web

Nota

Apabila merujuk kepada jadual Dataverse menggunakan API Web portal, anda perlu menggunakan EntitySetName, sebagai contoh, untuk mengakses jadual akaun, sintaks kod akan menggunakan EntitySetName akaun.

Rekod pertanyaan

Berikut ialah contoh pertanyaan rekod akaun:

Operasi Kaedah URI
Dapatkan rekod jadual MENDAPATKAN [Portal URI]/_api/accounts

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts

Contoh respons

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

Gunakan $select dan $top pertanyaan sistem untuk mengembalikan nama sifat untuk tiga akaun pertama:

Operasi Kaedah URI
Dapatkan semula tiga rekod entiti pertama MENDAPATKAN [Portal URI]/_api/accounts?$select=name,revenue&$top=3

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

Dapatkan semula akaun menggunakan ID akaun:

Operasi Kaedah URI
Dapatkan semula sifat khusus untuk rekod MENDAPATKAN [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name

Contoh respons

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

Gunakan pilihan pertanyaan sistem

Setiap pilihan pertanyaan sistem anda ditambah ke URL untuk set entiti ditambah menggunakan sintaks untuk rentetan pertanyaan. Yang pertama dilampirkan selepas [?] dan pilihan pertanyaan berikut dipisahkan menggunakan [&]. Semua pilihan pertanyaan adalah sensitif huruf seperti yang ditunjukkan dalam contoh berikut:

Kaedah URI
MENDAPATKAN [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3

Minta sifat tertentu

Gunakan pilihan pertanyaan sistem $select untuk mengehadkan sifat yang dikembalikan seperti ditunjukkan dalam contoh berikut:

Kaedah URI
MENDAPATKAN [Portal URI]/_api/accounts?$select=name,revenue&$top=3

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

Penting

Ini ialah amalan terbaik prestasi. Jika sifat tidak ditentukan dan anda telah mengkonfigurasi nilai tetapan tapak Webapi/<table name>/fields kepada *, maka semua sifat akan dikembalikan menggunakan $select. Jika tiada sifat dinyatakan, maka ralat akan dikembalikan.

Tapis hasil

Gunakan pilihan pertanyaan sistem $filter untuk menetapkan kriteria baris yang dikembalikan.

Operator penapis standard

API Web menyokong operator penapis OData standard yang disenaraikan dalam jadual berikut:

Pengendali Perihalan Sebagai contoh
Pengendali Perbandingan
eq Sama dengan $filter=persamaan hasil 100000
ne Tidak Sama $filter=hasil ne 100000
gt Lebih besar daripada $filter=hasil gt 100000
ge Lebih besar atau sama $filter=hasil ge 100000
lt Kurang daripada $filter=hasil lt 100000
le Kurang daripada atau sama $filter=hasil le 100000
Pengendali Logik
dan Logik dan $filter=hasil lt 100000 dan hasil gt 2000
or Logik atau $filter=mengandung(nama,'(sampel)') atau mengandung(nama,'ujian')
tidak Penafian logik $filter=tidak mengandungi (nama, 'sampel')
Pengendali Kumpulan
( ) Kumpulan duluan (mengandungi (nama,'sampel') atau mengandungi (nama,'ujian')) dan hasil gt 5000

Fungsi pertanyaan standard

API Web menyokong fungsi pertanyaan rentetan OData standard ini:

Fungsi Sebagai contoh
mengandungi $filter=mengandungi(nama,'(sampel)')
endswith $filter=endswith(nama,'Inc.')
startswith $filter=startswith(nama,'a')

Fungsi pertanyaan Dataverse

API Web menyokong fungsi pertanyaan Dataverse untuk menapis hasil. Untuk maklumat lanjut, lihat Rujukan Fungsi Pertanyaan API Web.

hasil tertib

Nyatakan tertib item yang dikembalikan menggunakan pilihan pertanyaan sistem $orderby. Gunakan akhiran naik atau turun untuk menentukan tertib menaik atau menurun masing-masing. Lalai adalah menaik jika akhiran tidak digunakan. Contoh berikut menunjukkan pengambilan nama dan sifat hasil akaun yang disusun mengikut hasil menaik dan mengikut nama menurun.

Kaedah URI
MENDAPATKAN [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000

Keputusan aggregat dan pengelompokan

Dengan menggunakan $apply anda boleh mengagregat dan mengelompokkan data anda secara dinamik seperti yang dilihat dalam contoh berikut:

Senario Sebagai contoh
Senarai status unik dalam pertanyaan akaun?$apply=groupby((statuscode))
Jumlah agregat nilai anggaran peluang?$apply=agregat(nilai anggaran dengan jumlah sebagai jumlah)
Saiz purata urusan berdasarkan anggaran nilai dan status peluang?$apply=groupby((statuscode),agregat(nilai anggaran dengan purata sebagai nilai purata)
Jumlah nilai anggaran berdasarkan status peluang?$apply=groupby((statuscode),aggregate(nilai anggaran dengan jumlah sebagai jumlah))
Jumlah hasil peluang mengikut nama akaun peluang?$apply=groupby((parentAccountId/Name),agregat(nilai anggaran dengan jumlah sebagai jumlah))
Nama kenalan utama untuk akaun dalam 'WA' akaun?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Tarikh dan masa rekod terakhir dibuat akaun?$apply=agregat(dibuat dengan maksimum sebagai lastCreate)
Tarikh dan masa rekod yang pertama dicipta akaun?$apply=agregat(dibuat dengan min sebagai firstCreate)

Mendapatkan kiraan baris

Gunakan pilihan pertanyaan sistem $count dengan nilai benar untuk memasukkan kiraan entiti yang sepadan dengan kriteria penapis sehingga 5,000.

Kaedah URI
MENDAPATKAN [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true

Contoh respons

{
"@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"
    }
]
}

Jika anda tidak mahu mengembalikan sebarang data kecuali untuk kiraan, anda boleh menggunakan $count pada sebarang koleksi untuk mendapatkan nilai sahaja.

Kaedah URI
MENDAPATKAN [Portal URI/_api/accounts/$count

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts/$count

Contoh respons

3

Perbandingan lajur

Contoh berikut menunjukkan cara membandingkan lajur menggunakan API Web:

Kaedah URI
GET [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname

Sebagai contoh:
https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname

Gunakan pilihan pertanyaan sistem $expand dalam sifat navigasi untuk mengawal data daripada entiti berkaitan yang dikembalikan.

Cari sifat navigasi yang berkaitan

Anda perlu menggunakan sifat Microsoft.Dynamics.CRM.associatednavigation sebagai atribut carian apabila menggunakan pilihan $expand pertanyaan.

Untuk menentukan Microsoft.Dynamics.CRM.associatednavigationproperty atribut, anda boleh membuat permintaan http GET berikut untuk lajur menggunakan konvensyen penamaan berikut: _name_value.

Dalam contoh berikut, kita boleh menentukan sifat navigasi yang berkaitan bagi lajur Kenalan Utama jadual Akaun dengan menyatakan nama lajur primarycontactid dengan memformatkan nama dalam permintaan:: _primarycontactid_value.

Kaedah URI
GET [Portal URI]/_api/accounts?$select=_primarycontactid_value

Sebagai contoh
https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value

Contoh respons

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

Kita melihat daripada respons bahawa sifat navigasi yang berkaitan ialah primarycontactid. Sifat navigasi yang berkaitan boleh merupakan sama ada nama logik atau nama skema lajur carian bergantung pada cara jadual dibuat.

Untuk maklumat lanjut, lihat Dapatkan semula data tentang sifat carian.

Contoh berikut menunjukkan cara untuk mendapatkan semula kenalan untuk semua rekod akaun. Untuk rekod kenalan yang berkaitan, kami hanya mendapatkan semula idkenalan dan namapenuh.

Kaedah URI
GET [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)

Contoh respons

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

Jika anda mengembangkan parameter navigasi bernilai koleksi untuk mendapatkan semula jadual berkaitan bagi set entiti, hanya satu tahap kedalaman dikembalikan jika terdapat data. Jika tidak, koleksi mengembalikan tatasusunan kosong.

Kaedah URI
MENDAPATKAN [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)

Contoh berikut menunjukkan cara anda boleh mengembangkan entiti berkaitan untuk set entiti menggunakan kedua-dua sifat navigasi bernilai tunggal dan koleksi. Anda perlu menentukan nama perhubungan jadual dalam sintaks kod anda.

Kaedah URI
MENDAPATKAN [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

Sebagai contoh:
https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)

Rekod pertanyaan menggunakan FetchXml

Hantar pertanyaan FetchXml sebagai nilai rentetan yang dikodkan URL kepada koleksi set entiti menggunakan parameter pertanyaan FetchXml.

Contohnya, untuk mendapatkan semula data daripada set entiti akaun, tulis pertanyaan FetchXml yang menetapkan parameter nama elemen entiti kepada akaun.

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

Rentetan yang dikodkan URL untuk pertanyaan sebelumnya ialah:

%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
Kaedah URI
MENDAPATKAN [Portal URI]/_api/accounts?fetchxml

Sebagai contoh:
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

Contoh respons

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

Langkah Seterusnya

Portal menulis, mengemas kini dan memadam operasi menggunakan API Web

Lihat juga