Bagikan melalui

Data kueri menggunakan API Web portal

  • Artikel

Catatan

Mulai 12 Oktober 2022, portal Power Apps menjadi Power Pages. Informasi selengkapnya: Microsoft Power Pages kini tersedia secara umum (blog)
Kami akan segera memigrasikan dan menggabungkan dokumentasi portal Power Apps dengan dokumentasi Power Pages.

Anda dapat menggunakan operasi api web yang tersedia di portal. 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 portal 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 GET [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 GET [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 GET [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 pilihan kueri berikut dipisahkan menggunakan [&]. Semua pilihan kueri peka huruf besar/kecil seperti ditunjukkan dalam contoh berikut:

Metode URI
GET [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 opsi kueri sistem $select untuk membatasi properti yang dikembalikan seperti yang diperlihatkan dalam contoh berikut:

Metode URI
GET [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 $filter kueri sistem untuk menetapkan kriteria baris mana yang akan 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=revenue eq 100000
ne Tidak sama dengan $filter=revenue ne 100000
gt Lebih dari $filter=revenue gt 100000
ge Lebih dari atau sama dengan $filter=revenue ge 100000
lt Kurang dari $filter=revenue lt 100000
le Kurang dari atau sama dengan $filter=revenue le 100000
operator logika
dan Logis and $filter=revenue lt 100000 and revenue gt 2000
or Logis or $filter=contains(name,'(sample)') or contains(name,'test')
bukan Negasi logis $filter=not contains(name,'sample')
Operator pengelompokan
( ) pengelompokan preseden (contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Fungsi kueri standar

API Web mendukung fungsi kueri string OData standar berikut:

Function Contoh
berisi $filter=contains(name,'(sample)')
endswith $filter=endswith(name,'Inc.')
startswith $filter=startswith(name,'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 item yang dikembalikan menggunakan opsi kueri sistem $orderby . Gunakan akhiran asc atau desc  untuk menentukan urutan naik atau turun 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
GET [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 menggabungkan dan mengelompokkan data Anda secara dinamis seperti yang terlihat dalam contoh berikut:

Skenario Contoh
Daftar status unik di kueri accounts?$apply=groupby((statuscode))
Jumlah agregat perkiraan nilai opportunities?$apply=aggregate(estimatedvalue with sum as total)
Ukuran rata-rata transaksi berdasarkan perkiraan nilai dan status opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Jumlah perkiraan nilai berdasarkan status opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Pendapatan peluang total berdasarkan nama akun opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Nama kontak utama untuk akun di 'WA' accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Tanggal dan waktu rekaman terakhir dibuat accounts?$apply=aggregate(createdon with max as lastCreate)
Tanggal dan waktu rekaman pertama kali dibuat accounts?$apply=aggregate(createdon with min as firstCreate)

Mengambil hitungan baris

 Gunakan opsi kueri sistem $count dengan nilai true untuk menyertakan hitungan entitas yang cocok dengan kriteria filter hingga 5.000.

Metode URI
GET [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 koleksi apa pun untuk mendapatkan nilainya.

Metode URI
GET [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

Mengambil rekaman tabel terkait dengan kueri

 Gunakan opsi kueri sistem$expand di properti navigasi untuk mengontrol data apa dari entitas terkait yang dikembalikan.

Properti navigasi tediarahkan pencarian

Anda harus menggunakan Microsoft.Dynamics.CRM.associatednavigationproperty sebagai atribut pencarian saat menggunakan pilihan 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 lebih lanjut lihat Mengambil data tentang properti pencarian.

Ambil rekaman tabel terkait dengan memperluas properti navigasi bernilai tunggal

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

Ambil tabel terkait dengan memperluas properti navigasi bernilai kumpulan

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, kumpulan akan mengembalikan larik kosong.

Metode URI
GET [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)

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

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

Metode URI
GET [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)

Langkah Berikutnya

Operasi Menulis, Memperbarui dan menghapus portal dengan menggunakan Web API

Baca juga

Ikhtisar API Web portal
Tutorial: Menggunakan API Web portal
Mengonfigurasi izin kolom

Catatan

Apa bahasa dokumentasi yang Anda inginkan? Lakukan survei singkat. (perlu diketahui bahwa survei ini dalam bahasa Inggris)

Survei akan berlangsung kurang lebih selama tujuh menit. Tidak ada data pribadi yang dikumpulkan (pernyataan privasi).