API Klien Power Pages (pratinjau)

[Artikel ini adalah dokumentasi prarilis dan dapat berubah.]

Power Pages API klien membantu pengembang memanipulasi komponen UI, mengelola formulir dan daftar, menangani autentikasi pengguna, dan berinteraksi dengan rekaman Dataverse secara terprogram. API klien tersedia saat halaman Anda dimuat dan dapat diakses melalui variabel global dengan nama yang Anda pilih.

Artikel ini menggunakan nama $pages variabel di seluruh contoh dan merekomendasikan Anda mengikuti konvensi penamaan ini untuk konsistensi.

Dengan API klien, Anda dapat:

$pages Dengan API klien, Anda dapat:

  • Mengambil dan memodifikasi formulir dan kontrol formulir
  • Perlihatkan atau sembunyikan elemen UI
  • Membuat dan mengambil rekaman menggunakan API Web
  • Mengelola autentikasi pengguna
  • Bekerja dengan konten multibahasa

Important

  • Ini adalah fitur pratinjau.
  • Fitur pratinjau tidak dimaksudkan untuk digunakan dalam produksi dan fungsinya mungkin terbatas. Fitur-fitur ini tunduk pada ketentuan penggunaan tambahan, dan tersedia sebelum rilis resmi sehingga pelanggan dapat memperoleh akses awal dan memberikan umpan balik.

Inisialisasi API Klien

$pages API klien tidak segera diinisialisasi saat halaman dimuat. Microsoft.Dynamic365.Portal.onPagesClientApiReady Gunakan fungsi untuk menetapkan objek API ke $pages variabel . Ada dua cara untuk menginisialisasi API klien:

Kesiapan API berbasis panggilan balik

Gunakan fungsi panggilan balik yang menetapkan objek API ke variabel yang Anda tentukan saat siap. Dua contoh menunjukkan cara:

Dengan menggunakan fungsi anonim:

Microsoft.Dynamic365.Portal.onPagesClientApiReady(($pages) => {
    const forms = $pages.currentPage.forms.getAll();
    console.log(`Found ${forms.length} forms on the page.`);
});

Dengan menggunakan fungsi bernama:

function start($pages){
    const forms = $pages.currentPage.forms.getAll();
    console.log(`Found ${forms.length} forms on the page.`);
}

Microsoft.Dynamic365.Portal.onPagesClientApiReady(start)

Kesiapan API berbasis promise/await

Menggunakan menunggu untuk menangani janji yang dikembalikan oleh Microsoft.Dynamic365.Portal.onPagesClientApiReady fungsi untuk alur asinkron yang lebih bersih.

let $pages = await Microsoft.Dynamic365.Portal.onPagesClientApiReady();
const forms = $pages.currentPage.forms.getAll();
console.log(`Found ${forms.length} forms on the page.`);

Kapan menggunakan setiap pendekatan

Tabel berikut ini menjelaskan kapan harus menggunakan setiap pendekatan.

Approach Kapan digunakan
Kesiapan API berbasis panggilan balik Gunakan saat Anda perlu mendukung browser lama atau skrip warisan yang tidak mendukung async/await, atau ketika Anda ingin mendaftarkan beberapa handler yang berjalan saat API siap. Ideal untuk pola berbasis peristiwa.
Kesiapan API berbasis promise/await Gunakan di lingkungan JavaScript modern yang mendukung async/await kode yang lebih bersih dan berurutan. Terbaik ketika logika Anda tergantung pada API yang siap sebelum melanjutkan eksekusi.

Tip

Jika basis kode Anda sudah menggunakan async/await, lebih suka pendekatan berbasis Promise untuk konsistensi.

koleksi $pages.currentPage.forms

Koleksi $pages.currentPage.forms mencakup metode untuk bekerja dengan elemen formulir di halaman.

metode $pages.currentPage.forms

Gunakan metode ini untuk mencantumkan formulir dan mendapatkan instans formulir tertentu.

Metode Returns Deskripsi
getAll IForm[] Mengembalikan semua formulir yang ditambahkan ke halaman saat ini.
getFormById(id: string) IForm Mengambil formulir dengan ID elemen HTML-nya.
getFormByName(name: string) IForm Mengambil formulir berdasarkan namanya.

contoh metode $pages.currentPage.forms

Contoh-contoh ini menunjukkan cara mendapatkan semua formulir dan mengambil formulir tertentu berdasarkan ID atau nama.

let forms = $pages.currentPage.forms.getAll();
let form1 = $pages.currentPage.forms.getFormById('form_#1');
let form2 = $pages.currentPage.forms.getFormByName('form_name')

Antarmuka IForm

Antarmuka IForm mewakili kontainer untuk kontrol dan tab.

Properti IForm

Properti berikut ini menjelaskan formulir dan kontrol dan tab yang terkandung.

Property Type Deskripsi
id string ID formulir.
name string Nama formulir.
controls Menguasai[] Semua kontrol pada formulir.
tabs Tab[] Semua tab pada formulir.
isMultiStep Boolean True jika formulirnya multistep; jika tidak, salah. Lihat Formulir multistep.

Metode IForm

Gunakan metode ini untuk mengkueri visibilitas formulir dan beralih apakah terlihat.

Metode Returns Deskripsi
getVisible boolean Mengembalikan true jika formulir terlihat; jika tidak, salah.
setVisible(isVisible: boolean) void Mengatur visibilitas formulir.

Contoh IForm

Contoh berikut mengambil formulir menurut ID dan mencatat visibilitas, jumlah kontrol, dan tabnya.

let form = $pages.currentPage.forms.getFormById('form_#1');

console.log(`Form id: ${form.id} has ${form.controls.length} controls.`); 

if (form.getVisible()) {  
console.log('Form is currently visible.');  
}  
let tabs = form.tabs;  
console.log(`Form has ${tabs.length} tabs.`);

Formulir multilangkah

Bentuk multistep adalah kontainer yang menyimpan beberapa formulir dasar.

Properti formulir multistep

Properti berikut berlaku untuk kontainer formulir multistep dan menjelaskan apa yang tersedia dalam langkah yang saat ini aktif.

Property Type Deskripsi
id string ID formulir multistep.
controls Menguasai[] Semua kontrol dalam langkah saat ini.
tabs Tab[] Semua tab dalam langkah saat ini.
isMultiStep Boolean True jika formulirnya multistep; jika tidak, salah.
nextButton Elemen JQuery Mewakili tombol berikutnya (objek kosong jika tidak ada).
previousButton Elemen JQuery Mewakili tombol sebelumnya (objek kosong jika tidak ada).

Metode formulir multistep

Gunakan metode ini untuk memeriksa visibilitas dan berpindah di antara langkah-langkah dalam bentuk multistep.

Nama Returns Deskripsi
getVisible boolean Mengembalikan true jika formulir terlihat; jika tidak, salah.
setVisible(isVisible: boolean) void Mengatur visibilitas formulir.
isVisible boolean Properti yang menunjukkan apakah formulir harus ditampilkan (benar) atau tersembunyi (false).
hasNextStep boolean Mengembalikan true jika ada langkah berikutnya; jika tidak, salah.
hasPreviousStep boolean Mengembalikan true jika ada langkah sebelumnya; jika tidak, salah.
goToNextStep void Menavigasi ke langkah berikutnya; mengirimkan formulir jika tidak ada langkah berikutnya.
goToPreviousStep void Menavigasi ke langkah sebelumnya; melemparkan pengecualian jika tidak ada.

Contoh formulir multistep

Contoh ini menunjukkan cara mengambil formulir multistep, memeriksanya, dan melanjutkan ke langkah berikutnya.

let $pages = await Microsoft.Dynamic365.Portal.onPagesClientApiReady();
let form = $pages.currentPage.forms.getFormById('multiform_#1');
console.log(`Form id: ${form.id} has ${form.controls.length} controls.`);

if (form.getVisible()) {
console.log('Form is currently visible.');
}

let tabs = form.tabs;
console.log(`Form has ${tabs.length} tabs.`);

form.goToNextStep();

Tab

berisi Tab satu atau beberapa bagian dalam formulir.

Properti tab Sections

Array bagian dalam tab.

Metode tab

Gunakan metode ini untuk memeriksa visibilitas tab, mengambil namanya, dan beralih apakah terlihat.

Metode Returns Deskripsi
getVisible boolean Mengembalikan true jika tab terlihat; jika tidak, salah.
getName string Mengembalikan nama tab.
setVisible(isVisible: boolean) void Mengatur visibilitas tab.

Contoh tab

Contoh ini mengambil formulir, menghitung tabnya, dan mencatat nama tab pertama.

let form = $pages.currentPage.forms.getFormById('form_#1');  
let tabs = form.tabs;  
console.log(`Form has ${tabs.length} tabs.`);  
console.log(`First tab is named: ${tabs[0].getName()}`);

Section

Bagian kontrol grup dalam tab.

Properti bagian Controls

Array kontrol di dalam bagian .

Metode bagian

Gunakan metode ini untuk membaca nama bagian dan mengontrol visibilitasnya.

Metode Returns Deskripsi
getVisible boolean Mengembalikan true jika bagian terlihat; jika tidak, salah.
getName string Mengembalikan nama bagian.
setVisible(isVisible: boolean) void Mengatur visibilitas bagian.

Contoh bagian

Contoh ini mengambil bagian dari tab pertama formulir dan log detail dasar.

let form = $pages.currentPage.forms.getFormById('form_#1');  
let sections = form.tabs[0].sections;  
console.log(`Tab has ${sections.length} section(s).`);  
console.log(`First section is named: ${sections[0].getName()}`);

Kontrol

Kontrol mewakili elemen formulir individual.

Metode kontrol

Gunakan metode ini untuk mengambil atau memperbarui nilai kontrol, visibilitas, dan status yang dinonaktifkan.

Metode Returns Deskripsi
getDisabled boolean Mengembalikan true jika kontrol dinonaktifkan.
getVisible boolean Mengembalikan true jika kontrol terlihat.
getName string Mengembalikan nama kontrol.
getValue string | undefined Mengambil nilai saat ini.
setDisabled(isDisabled: boolean) void Mengatur status dinonaktifkan.
setVisible(isVisible: boolean) void Mengatur visibilitas.
setValue(value: string) void Mengatur nilai baru untuk kontrol.

Contoh kontrol

Contoh ini mengambil formulir, memeriksa visibilitas kontrol pertama, lalu menyembunyikannya.

let form = $pages.currentPage.forms.getFormById('form_#1');  
let controls = form.controls;  
if (controls.length > 0) {  
if (controls[0].getVisible()) {  
console.log(`Control ${controls[0].getName()} is visible.`);  
}  
controls[0].setVisible(false); // Hide the first control.  
}

Kontrol yang didukung

Semua kontrol menerapkan metode kontrol standar. Beberapa kontrol menyediakan lebih banyak metode dan memiliki detail implementasi yang berbeda dari metode kontrol standar. Pelajari tentang metode lain dan perbedaan implementasi untuk berbagai jenis kontrol.

koleksi $pages.currentPage.lists

Kumpulan daftar menyediakan metode untuk bekerja dengan elemen daftar tradisional dan modern di halaman.

metode $pages.currentPage.lists

Gunakan metode ini untuk menghitung semua daftar di halaman dan mendapatkan daftar tertentu berdasarkan ID elemen HTML-nya.

Metode Returns Deskripsi
getAll IList[] Mengembalikan semua daftar pada halaman saat ini.
getListById(id: string) IList Mendapatkan daftar berdasarkan ID elemen HTML-nya.

contoh $pages.currentPage.lists

Contoh-contoh ini menunjukkan cara menghitung semua daftar di halaman dan mendapatkan daftar tertentu berdasarkan ID elemen HTML-nya.

let lists = $pages.currentPage.lists.getAll();
let list = $pages.currentPage.lists.getListById('list_#1');

Antarmuka IList

Daftar mewakili komponen data tabular atau seperti kisi.

Properti IList

Properti ini mengidentifikasi daftar dan menunjukkan apakah ia menggunakan model penyajian modern.

Property Type Deskripsi
id string Pengidentifikasi unik daftar.
isModern Boolean Nilai Boolean yang benar untuk daftar modern dan salah jika tidak.

Metode IList

Gunakan metode ini untuk memeriksa visibilitas daftar, beralih apakah terlihat, dan mengakses elemen HTML yang mendasar.

Metode Returns Deskripsi
getVisible boolean Mengembalikan true jika daftar terlihat.
setVisible(isVisible: boolean) void Mengatur visibilitas daftar.
getHtmlElement HTMLElement Mengembalikan elemen HTML yang mendasar untuk daftar.

Contoh IList

Contoh berikut mengambil daftar menurut ID dan mencatat status visibilitasnya.

let list = $pages.currentPage.lists.getListById('list_#1');  
console.log(`List id: ${list.id}`);  
if (list.getVisible()) {  
console.log('List is currently visible.');  
}

objek $pages.user

Objek $pages.user menyediakan metode untuk memasukkan atau mengeluarkan pengguna.

metode $pages.user

Metode ini tidak mengembalikan nilai apa pun.

Metode Deskripsi
signIn Mengalihkan pengguna ke halaman masuk.
signOut Keluar dari pengguna yang saat ini masuk.

objek $pages.webAPI

Objek $pages.webAPI menyediakan metode untuk membuat dan mengambil rekaman dari sumber data.

metode createRecord

Membuat rekaman baru dalam tabel yang ditentukan.

Sintaks: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<object>
Mengembalikan: Janji yang diselesaikan ke rekaman atau hasil operasi yang dibuat.

parameter metode createRecord

Berikan tabel target dan objek data yang mewakili rekaman yang akan dibuat.

Parameter Type Deskripsi
entitySetName string Nama kumpulan entitas. Pelajari tentang nama kumpulan entitas di Dataverse Web API
data objek Data rekaman yang akan dibuat.

contoh metode createRecord

Contoh ini menunjukkan panggilan createRecord dengan nama kumpulan entitas dan objek data minimal.

$pages.webAPI.createRecord('contacts', {  
firstName: 'User',
lastName: 'Test'  
});

metode retrieveRecord

Mengambil rekaman dengan pengidentifikasi uniknya.

Sintaks: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Mengembalikan: Janji yang diselesaikan ke objek rekaman.

parameter metode retrieveRecord

Tentukan tabel, ID rekaman, dan opsi kueri OData $select opsional untuk membentuk respons.

Parameter Type Deskripsi
entitySetName string Nama kumpulan entitas. Pelajari tentang nama kumpulan entitas di Dataverse Web API.
id string Pengidentifikasi unik rekaman.
options string (opsional) String kueri OData $select opsional untuk membatasi data yang dikembalikan.

Note

options Meskipun parameter bersifat opsional, untuk performa terbaik selalu batasi jumlah nilai kolom yang dikembalikan dengan menggunakan $select opsi .

contoh metode retrieveRecord

Contoh ini mengambil satu rekaman menurut ID dan membatasi kolom yang dikembalikan dengan menggunakan opsi kueri OData $select .

let record = await $pages.webAPI.retrieveRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',  '$select=name');

metode retrieveMultipleRecords

Mengambil beberapa rekaman berdasarkan opsi kueri yang disediakan.

Sintaks: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Mengembalikan: Janji yang diselesaikan ke array objek rekaman.

parameter metode retrieveMultipleRecords

Tentukan tabel dan kueri OData opsional untuk memfilter hasil dan membatasi kolom yang dikembalikan.

Parameter Type Deskripsi
entitySetName string Nama kumpulan entitas.
options string (opsional) String opsi kueri OData untuk mengontrol data yang dikembalikan. Pelajari selengkapnya tentang opsi kueri OData yang didukung oleh Dataverse Web API

Note

options Meskipun parameter bersifat opsional, untuk performa terbaik selalu batasi jumlah nilai kolom yang dikembalikan dengan menggunakan $select opsi .

contoh metode retrieveMultipleRecords

Contoh ini mengambil beberapa rekaman dan menggunakan OData $select dan $top untuk membatasi kolom dan jumlah baris yang dikembalikan.

let records = await $pages.webAPI.retrieveMultipleRecords('accounts','$select=name&$top=3');

$pages.languages

Objek menyediakan $pages.languages metode untuk mengambil daftar bahasa yang tersedia untuk situs web, mendapatkan bahasa yang saat ini aktif, dan mengatur bahasa aktif baru.

metode $pages.languages

Gunakan metode ini untuk membaca bahasa yang tersedia, memeriksa bahasa saat ini, dan mengubahnya untuk situs.

Metode Deskripsi Returns
getAll Mengambil daftar bahasa yang diaktifkan untuk situs web. string[]
getActive Mengambil bahasa yang saat ini aktif. string
setActive(language: string) Mengatur bahasa yang diberikan sebagai bahasa aktif. void

Note

setActive metode menyebabkan reload halaman.

contoh metode $pages.languages

Contoh-contoh ini menunjukkan cara mencantumkan semua bahasa, membaca bahasa aktif, dan mengatur bahasa aktif baru.

let allLanguages = $pages.languages.getAll();
let activeLanguage = $pages.languages.getActive();
$pages.languages.setActive('hi-IN');

$pages.agent

Objek $pages.agent menyediakan metode untuk membangun komunikasi antara situs dan agen Microsoft Copilot Studio yang tersedia untuk pengguna saat ini.

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);
Nama Parameter Type Deskripsi
agentSchemaName String Nama skema bot tempat aktivitas dikirim.
inputActivity Objek Objek yang berisi teks atau peristiwa untuk dikirim ke bot.
responseSubscriber fungsi Fungsi panggilan balik yang berjalan saat agen mengirim respons.
errorSubscriber fungsi Fungsi panggilan balik yang menangani kesalahan.

Jenis pengembalian: batal - Fungsi tidak mengembalikan apa pun.

Objek respons dari agen yang diterima dalam format berikut:

Nama Type Deskripsi
type String Jenis aktivitas seperti pesan.
text String Opsional, pesan dari agen.
textFormat String Opsional, format teks pesan seperti markdown, polos, atau XML.
Id String ID yang secara unik mengidentifikasi aktivitas.
From Objek Menentukan pengirim aktivitas (termasuk id, nama (opsional), dan informasi peran).
Conversation Objek Berisi ID percakapan tempat aktivitas berada.
InputHint String Opsional, menunjukkan apakah bot menerima, mengharapkan, atau mengabaikan input pengguna.
replyToId String ID pesan balasan.

Example

Metode panggilan balik

responseSubscriber Tentukan fungsi panggilan balik dan errorSubscriber untuk menangani respons dan kesalahan agen.

const responseSubscriber = (response) => {  
// Replace with your response handling.
console.log('Agent response:', response);
};

const errorSubscriber = (error) => {
// Replace with your error handling.
console.error('Error:', error);
};  

// Replace with your agent schema name.
const agentSchemaName = 'agent SchemaName';

Mengirim pesan ke agen

const inputActivity = {
    text: 'Hello!', // Message to the agent.
    };

$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, 
  ErrorSubscriber);

Memanggil peristiwa klien

const inputActivity = {
    name: 'AgentEvent', // The name of the event to be invoked
    value: {key1:'value1', key2:'value2'} // Open-ended value used to carry additional data or payloads necessary for specific agent operations or responses
    };

$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, 
  ErrorSubscriber);

Pesan kesalahan

Berikut adalah kemungkinan pesan kesalahan yang dapat ditemui pengguna dan potensi penyebabnya.

Jenis kesalahan Sebab Pesan kesalahan untuk pengguna
Validasi skema agen Nama skema bot yang disediakan tidak valid atau pengguna tidak memiliki izin akses ke agen Invalid bot schema name or access denied. Please check the bot schema name and try again.
Mengambil kesalahan token Terjadi kesalahan saat mengambil token baris langsung Something went wrong while fetching the token. Please try again.
Kesalahan aktivitas postingan (coba lagi) Terjadi kesalahan saat memposting aktivitas dan percobaan ulang diperlukan. Something went wrong while posting the activity: retry.
Kesalahan aktivitas postingan (waktu habis) Waktu habis saat menunggu pesan keluar atau postActivity Timed out while posting activity: Please retry.
Kesalahan aktivitas postingan (aktivitas tidak valid) Aktivitas input tidak memiliki teks atau nama untuk memanggil peristiwa. Invalid activity: At least one of text, name, or attachments must be provided.
Kesalahan aktivitas posting (ID pengguna tidak ditemukan atau token tidak ditemukan) Token tidak ditemukan di penyimpanan sesi atau ID pengguna tidak ditemukan dalam token Error retrieving user ID: {error message}
Memposting kesalahan aktivitas (umum) Terjadi kesalahan yang tidak ditentukan saat memposting aktivitas Something went wrong while posting the activity: Please try again.
Kesalahan koneksi saluran langsung Terjadi kesalahan saat membuat koneksi baris langsung dengan bot. Something went wrong while creating direct line connection: Please try again.
Kesalahan umum Kesalahan tak terduga yang tidak termasuk dalam kategori di atas An unexpected error occurred while sending activity: Please try again.
  • Last updated on