Data kueri menggunakan API Web portal

Artikel
12/24/2024

Anda dapat menggunakan operasi api web yang tersedia di portal Power Pages. Operasi API web terdiri dari permintaan dan respons HTTP. Artikel ini memberikan operasi baca sampel, metode, URI, dan JSON sampel yang dapat Anda gunakan dalam permintaan HTTP.

Prasyarat

Versi situs web Anda harus 9.4.1.x atau yang lebih tinggi.
Aktifkan tabel dan bidang untuk operasi Web API. Informasi lebih lanjut, lihat pengaturan situs untuk API Web.
API Web portal mengakses rekaman tabel dan mengikuti izin tabel yang diberikan kepada pengguna melalui peran web terkait. Pastikan Anda mengkonfigurasi izin tabel yang benar. Informasi selengkapnya: Membuat peran web.

Catatan

Bila merujuk ke tabel Dataverse menggunakan API Web portal, Anda harus menggunakan EntitySetName, contohnya,untuk mengakses tabel akun, sintaks kode akan menggunakan EntitySetName dari akun.

Rekaman kueri

Contoh berikut mengkueri rekaman akun:

Operasi	Metode	URI
Ambil rekaman tabel	DAPAT	`[Portal URI]/_api/accounts` 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 opsi kueri sistem $select dan $top untuk menghasilkan properti nama tiga akun pertama:

Operasi	Metode	URI
Ambil tiga rekaman entitas pertama	DAPAT	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Contoh: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Ambil akun dengan menggunakan ID akun:

Operasi	Metode	URI
Ambil properti spesifik untuk rekaman	DAPAT	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` 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"
}

Menerapkan pilihan kueri sistem

Setiap pilihan kueri sistem yang Anda lampirkan ke URL untuk rangkaian entitas ditambahkan menggunakan sintaks untuk string kueri. Yang pertama ditambahkan setelah [?] dan opsi kueri berikut dipisahkan menggunakan [&]. Semua pilihan kueri peka huruf besar/kecil seperti ditunjukkan dalam contoh berikut:

Metode	URI
DAPAT	`[Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3` Contoh: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3`

Properti permintaan spesifik

Gunakan pilihan $select kueri sistem untuk membatasi properti yang dikembalikan seperti ditunjukkan dalam contoh berikut:

Metode	URI
DAPAT	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Contoh: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Penting

Ini adalah Praktik terbaik performa. Jika properti tidak ditentukan dan Anda telah mengkonfigurasikan nilai pengaturan situs Webapi/<table name>/fields ke *, maka semua properti akan dihasilkan menggunakan $select. Jika tidak ada properti yang ditentukan, maka kesalahan akan dihasilkan.

Filter hasil

Gunakan opsi kueri sistem $filter untuk mengatur kriteria baris yang dikembalikan.

Operator filter standar

API Web mendukung operator filter OData standar yang tercantum dalam tabel berikut:

Operator	Keterangan	Contoh
Operator Perbandingan
eq	Sama dengan	$filter=persamaan pendapatan 100000
ne	Tidak sama dengan	$filter=pendapatan ne 100000
gt	Lebih dari	$filter=pendapatan gt 100000
ge	Lebih dari atau sama dengan	$filter=pendapatan ge 100000
lt	Kurang dari	$filter=pendapatan lt 100000
le	Kurang dari atau sama dengan	$filter=pendapatan le 100000
Operator Logis
dan	Logis and	$filter=pendapatan lt 100000 dan pendapatan gt 2000
or	Logis or	$filter=contains(nama,'(sampel)') atau contains(nama,'uji')
bukan	Negasi logis	$filter=tidak berisi (nama,'sampel')
Operator Pengelompokan
( )	pengelompokan preseden	(berisi(nama,'sampel') atau berisi(nama,'tes')) dan pendapatan gt 5000

Fungsi kueri standar

API Web mendukung fungsi kueri string OData standar berikut:

Fungsi	Contoh
berisi	$filter=berisi(nama,'(sampel)')
endswith	$filter=endswith(nama,'Inc.')
startswith	$filter=startswith(nama,'a')

Fungsi kueri Dataverse

Web API mendukung fungsi kueri Dataverse untuk memfilter hasil. Untuk informasi lebih lanjut, lihat Referensi Fungsi Kueri WEB API.

Hasil pengurutan

Tentukan urutan pengembalian item menggunakan pilihan kueri sistem $orderby. Gunakan akhiran asc atau desc untuk menentukan urutan menaik atau menurun masing-masing. Default akan menaik jika akhiran tidak diterapkan. Contoh berikut menunjukkan pengambilan nama dan properti pendapatan akun yang diurutkan dengan menaik pendapatan dan turun nama.

Metode	URI
DAPAT	`[Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000` Contoh: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000`

Mengagregat dan mengelompokkan hasil

Dengan menggunakan $apply, Anda dapat mengagregat dan mengelompokkan data secara dinamis seperti terlihat dalam contoh berikut:

Skenario	Contoh
Daftar status unik di kueri	akun?$apply=groupby((kode status))
Jumlah agregat perkiraan nilai	peluang?$apply=agregat(nilai perkiraan dengan jumlah sebagai total)
Ukuran rata-rata transaksi berdasarkan perkiraan nilai dan status	peluang?$apply=groupby((statuscode),aggregate(estimatedvalue dengan rata-rata sebagai rata-rata nilai)
Jumlah perkiraan nilai berdasarkan status	peluang?$apply=groupby((statuscode),aggregate(estimatedvalue dengan jumlah sebagai total))
Pendapatan peluang total berdasarkan nama akun	peluang?$apply=groupBy((parentAccountId/Name),aggregate(estimatedValue dengan jumlah sebagai total))
Nama kontak utama untuk akun di 'WA'	akun?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Tanggal dan waktu rekaman terakhir dibuat	akun?$apply=aggregate(dibuat dengan maks sebagai lastCreate)
Tanggal dan waktu rekaman pertama kali dibuat	akun?$apply=aggregate(dibuaton dengan min sebagai firstCreate)

Mengambil hitungan baris

Gunakan opsi kueri sistem $count dengan nilai benar untuk mencakup jumlah entitas yang cocok dengan kriteria filter hingga 5.000.

Metode	URI
DAPAT	`[Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true` 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 ingin mengembalikan data apa pun kecuali untuk hitungan, Anda dapat menerapkan $count ke kumpulan apa pun untuk hanya mendapatkan nilai.

Metode	URI
DAPAT	`[Portal URI/_api/accounts/$count` Contoh: `https://contoso.powerappsportals.com/_api/accounts/$count`

Contoh respons

3

Perbandingan kolom

Contoh berikut menunjukkan cara membandingkan kolom menggunakan WEB API:

Metode	URI
GET	`[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname` Contoh: `https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname`

Gunakan pilihan kueri sistem $expand di properti navigasi untuk mengontrol data dari entitas terkait yang dihasilkan.

Anda perlu menggunakan properti Microsoft.Dynamics.CRM.associatednavigation sebagai atribut pencarian saat menggunakan opsi kueri $expand .

Untuk menentukan Microsoft.Dynamics.CRM.associatednavigationproperty atribut, Anda dapat membuat permintaan http GET berikut untuk kolom menggunakan aturan penamaan berikut: _name_value.

Pada contoh berikut, kita dapat menentukan properti navigasi terkait dari kolom Kontak Utama pada tabel Akun dengan menentukan nama kolom primarycontactid dengan memformat nama pada permintaan: _primarycontactid_value.

Metode	URI
GET	`[Portal URI]/_api/accounts?$select=_primarycontactid_value` 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 lihat dari respons yang terkait dengan properti navigasi adalah primarycontactid. Properti navigasi yang terkait dapat berupa nama logis atau nama skema kolom pencarian, tergantung pada cara tabel dibuat.

Untuk informasi selengkapnya, lihat Mengambil data tentang properti pencarian.

Contoh berikut menunjukkan cara mengambil kontak untuk semua rekaman akun. Untuk rekaman kontak terkait, kami hanya mengambil contactid dan fullname.

Metode	URI
GET	`[Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)` 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 memperluas parameter navigasi bernilai kumpulan untuk mengambil tabel terkait untuk rangkaian entitas, hanya satu tingkat kedalaman yang akan dikembalikan jika ada data. Jika tidak, koleksi mengembalikan array kosong.

Metode	URI
DAPAT	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)` Contoh: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)`

Contoh berikut memperlihatkan bagaimana Anda dapat memperluas entitas terkait untuk rangkaian entitas menggunakan properti navigasi bernilai tunggal maupun kumpulan. Anda perlu menentukan nama relasi tabel dalam sintaks kode Anda.

Metode	URI
DAPAT	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)` Contoh: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)`

Kueri rekaman menggunakan FetchXml

Teruskan kueri FetchXml sebagai nilai string yang dikodekan URL ke koleksi set entitas menggunakan parameter kueri FetchXml.

Misalnya, untuk mengambil data dari kumpulan entitas akun, buat kueri FetchXml yang mengatur parameter nama elemen entitas ke akun.

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

String yang dikodekan URL untuk kueri sebelumnya adalah:

%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

Metode	URI
DAPAT	`[Portal URI]/_api/accounts?fetchxml` 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 Berikutnya

Operasi penulisan, pembaruan, dan penghapusan portal menggunakan API Web

Bagikan melalui

Data kueri menggunakan API Web portal

Prasyarat

Rekaman kueri

Menerapkan pilihan kueri sistem

Properti permintaan spesifik

Filter hasil

Operator filter standar

Fungsi kueri standar

Fungsi kueri Dataverse

Hasil pengurutan

Mengagregat dan mengelompokkan hasil

Mengambil hitungan baris

Perbandingan kolom

Properti navigasi tediarahkan pencarian

Kueri rekaman menggunakan FetchXml

Langkah Berikutnya

Baca juga

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Data kueri menggunakan API Web portal

Prasyarat

Rekaman kueri

Menerapkan pilihan kueri sistem

Properti permintaan spesifik

Filter hasil

Operator filter standar

Fungsi kueri standar

Fungsi kueri Dataverse

Hasil pengurutan

Mengagregat dan mengelompokkan hasil

Mengambil hitungan baris

Perbandingan kolom

Mengambil rekaman tabel terkait dengan kueri

Properti navigasi tediarahkan pencarian

Ambil rekaman tabel terkait dengan memperluas properti navigasi bernilai tunggal

Ambil tabel terkait dengan memperluas properti navigasi bernilai kumpulan

Ambil tabel terkait dengan memperluas baik properti navigasi bernilai kumpulan maupun bernilai tunggal

Kueri rekaman menggunakan FetchXml

Langkah Berikutnya

Baca juga

Saran dan Komentar

Sumber Daya Tambahan: