API προγράμματος-πελάτη Power Pages (προεπισκόπηση)

[Αυτό το άρθρο αποτελεί τεκμηρίωση προέκδοσης και ενδέχεται να αλλάξει.]

Power Pages API προγράμματος-πελάτη βοηθούν τους προγραμματιστές να χειρίζονται στοιχεία περιβάλλοντος εργασίας χρήστη, να διαχειρίζονται φόρμες και λίστες, να χειρίζονται τον έλεγχο ταυτότητας χρήστη και να αλληλεπιδρούν με εγγραφές του Dataverse μέσω προγραμματισμού. Το API προγράμματος-πελάτη γίνεται διαθέσιμο όταν φορτώνεται η σελίδα σας και μπορείτε να αποκτήσετε πρόσβαση μέσω μιας καθολικής μεταβλητής με το όνομα που επιλέγετε.

Αυτό το άρθρο χρησιμοποιεί το όνομα $pages της μεταβλητής σε όλα τα παραδείγματα και συνιστά να ακολουθήσετε αυτήν τη σύμβαση ονοματοθεσίας για λόγους συνέπειας.

Με τα API προγράμματος-πελάτη, μπορείτε να κάνετε τα εξής:

Με το API προγράμματος-πελάτη $pages , μπορείτε να κάνετε τα εξής:

• Ανάκτηση και τροποποίηση φορμών και στοιχείων ελέγχου φόρμας
• Εμφάνιση ή απόκρυψη στοιχείων περιβάλλοντος εργασίας χρήστη
• Δημιουργία και ανάκτηση εγγραφών με χρήση του Web API
• Διαχείριση ελέγχου ταυτότητας χρήστη
• Εργασία με πολύγλωσσο περιεχόμενο

Σημαντικό

• Αυτή είναι μια δυνατότητα προεπισκόπησης.
• Οι δυνατότητες προεπισκόπησης δεν προορίζονται για χρήση στην παραγωγή και μπορεί να έχουν περιορισμένη λειτουργικότητα. Αυτές οι δυνατότητες υπόκεινται σε συμπληρωματικούς όρους χρήσης και διατίθενται πριν από μια επίσημη κυκλοφορία, έτσι ώστε οι πελάτες να μπορούν να αποκτήσουν πρώιμη πρόσβαση και να παρέχουν σχόλια.

Προετοιμασία API προγράμματος-πελάτη

Το $pages API προγράμματος-πελάτη δεν αρχικοποιείται αμέσως όταν φορτώνει η σελίδα. Χρησιμοποιήστε τη Microsoft.Dynamic365.Portal.onPagesClientApiReady συνάρτηση για να αντιστοιχίσετε το αντικείμενο API στη $pages μεταβλητή. Υπάρχουν δύο τρόποι προετοιμασίας του API προγράμματος-πελάτη:

Ετοιμότητα API βάσει επιστροφής κλήσης

Χρησιμοποιήστε μια συνάρτηση επιστροφής κλήσης που αντιστοιχίζει το αντικείμενο API σε μια μεταβλητή που ορίζετε όταν είναι έτοιμο. Δύο παραδείγματα δείχνουν πώς:

Χρησιμοποιώντας μια ανώνυμη συνάρτηση:

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

Χρησιμοποιώντας μια επώνυμη συνάρτηση:

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

Microsoft.Dynamic365.Portal.onPagesClientApiReady(start)

Ετοιμότητα API με βάση τις υποσχέσεις/αναμονής

Χρησιμοποιεί το await για να χειριστεί την υπόσχεση που επιστρέφεται από τη Microsoft.Dynamic365.Portal.onPagesClientApiReady λειτουργία για μια καθαρότερη ασύγχρονη ροή.

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

Πότε να χρησιμοποιείτε κάθε προσέγγιση

Ο παρακάτω πίνακας περιγράφει πότε πρέπει να χρησιμοποιείτε κάθε προσέγγιση.

Προσέγγιση	Πότε να χρησιμοποιήσετε
Ετοιμότητα API βάσει επιστροφής κλήσης	Χρησιμοποιήστε το όταν θέλετε να υποστηρίξετε παλαιότερα προγράμματα περιήγησης ή δέσμες ενεργειών παλαιού τύπου που δεν υποστηρίζουν async/awaitή όταν θέλετε να καταχωρήσετε πολλούς χειρισμούς που εκτελούνται όταν το API είναι έτοιμο. Ιδανικό για μοτίβα που βασίζονται σε συμβάντα.
Ετοιμότητα API με βάση τις υποσχέσεις/αναμονής	Χρησιμοποιήστε τα σε σύγχρονα περιβάλλοντα JavaScript που υποστηρίζουν async/await πιο καθαρό και διαδοχικό κώδικα. Το καλύτερο όταν η λογική σας εξαρτάται από την ετοιμότητα του API πριν από τη συνέχιση της εκτέλεσης.

Συμβουλή

Εάν η βάση κώδικα χρησιμοποιεί async/awaitήδη το , προτιμήστε την προσέγγιση που βασίζεται σε Υποσχέσεις για συνέπεια.

Συλλογή $pages.currentPage.forms

Η $pages.currentPage.forms συλλογή περιλαμβάνει μεθόδους για να εργαστείτε με στοιχεία φόρμας στη σελίδα.

Μέθοδοι $pages.currentPage.forms

Χρησιμοποιήστε αυτές τις μεθόδους για να παραλάβετε φόρμες και να λάβετε συγκεκριμένες παρουσίες φόρμας.

Μέθοδος	Επιστροφές	Περιγραφή
getAll	IForm[]	Επιστρέφει όλες τις φόρμες που έχουν προστεθεί στην τρέχουσα σελίδα.
getFormById(id: string)	IForm	Ανακτά μια φόρμα από το αναγνωριστικό στοιχείου HTML της.
getFormByName(name: string)	IForm	Ανακτά μια φόρμα με το όνομά της.

Παραδείγματα μεθόδου $pages.currentPage.forms

Αυτά τα παραδείγματα δείχνουν πώς μπορείτε να λάβετε όλες τις φόρμες και να ανακτήσετε συγκεκριμένες φόρμες με το αναγνωριστικό ή το όνομα.

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

Διασύνδεση IForm

Η IForm διασύνδεση αντιπροσωπεύει ένα κοντέινερ για στοιχεία ελέγχου και καρτέλες.

Ιδιότητες IForm

Οι παρακάτω ιδιότητες περιγράφουν τη φόρμα και τα στοιχεία ελέγχου και τις καρτέλες που περιέχονται.

Property	Τύπος	Περιγραφή
id	συμβολοσειρά	Το αναγνωριστικό της φόρμας.
name	συμβολοσειρά	Το όνομα της φόρμας.
controls	Έλεγχος[]	Όλα τα στοιχεία ελέγχου στη φόρμα.
tabs	Καρτέλα[]	Όλες οι καρτέλες στη φόρμα.
isMultiStep	δυαδική τιμή	True εάν η φόρμα είναι πολλαπλών βημάτων. διαφορετικά, false. Ανατρέξτε στο θέμα Φόρμα πολλαπλών βημάτων.

Μέθοδοι IForm

Χρησιμοποιήστε αυτές τις μεθόδους για να υποβάλετε ερωτήματα για την ορατότητα μιας φόρμας και νααλλάετε εάν είναι ορατή.

Μέθοδος	Επιστροφές	Περιγραφή
getVisible	boolean	Επιστρέφει την τιμή true εάν η φόρμα είναι ορατή. διαφορετικά, false.
setVisible(isVisible: boolean)	void	Ορίζει την ορατότητα της φόρμας.

Παράδειγμα IForm

Το παρακάτω παράδειγμα ανακτά μια φόρμα βάσει αναγνωριστικού και καταγράφει την ορατότητά της, τον αριθμό των στοιχείων ελέγχου και τις καρτέλες.

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

Φόρμα πολλών βημάτων

Μια φόρμα πολλαπλών βημάτων είναι ένα κοντέινερ που περιέχει πολλές βασικές φόρμες.

Ιδιότητες φόρμας πολλών βημάτων

Οι ακόλουθες ιδιότητες ισχύουν για το κοντέινερ φόρμας πολλαπλών βημάτων και περιγράφουν τι είναι διαθέσιμο στο τρέχον ενεργό βήμα.

Property	Τύπος	Περιγραφή
id	συμβολοσειρά	Το αναγνωριστικό της φόρμας πολλαπλών βημάτων.
controls	Έλεγχος[]	Όλα τα στοιχεία ελέγχου στο τρέχον βήμα.
tabs	Καρτέλα[]	Όλες οι καρτέλες στο τρέχον βήμα.
isMultiStep	δυαδική τιμή	True εάν η φόρμα είναι πολλαπλών βημάτων. διαφορετικά, false.
nextButton	JQuery Element	Αντιπροσωπεύει το επόμενο κουμπί (κενό αντικείμενο εάν απουσιάζει).
previousButton	JQuery Element	Αντιπροσωπεύει το προηγούμενο κουμπί (κενό αντικείμενο εάν απουσιάζει).

Μέθοδοι φόρμας πολλών βημάτων

Χρησιμοποιήστε αυτές τις μεθόδους για να ελέγξετε την ορατότητα και να μετακινηθείτε μεταξύ των βημάτων σε μια φόρμα πολλαπλών βημάτων.

Πλήρες όνομα	Επιστροφές	Περιγραφή
getVisible	boolean	Επιστρέφει την τιμή true εάν η φόρμα είναι ορατή. διαφορετικά, false.
setVisible(isVisible: boolean)	void	Ορίζει την ορατότητα της φόρμας.
isVisible	boolean	Ιδιότητα που υποδεικνύει εάν η φόρμα πρέπει να εμφανίζεται (true) ή κρυφό (false).
hasNextStep	boolean	Επιστρέφει την τιμή true εάν υπάρχει επόμενο βήμα. διαφορετικά, false.
hasPreviousStep	boolean	Επιστρέφει την τιμή true εάν υπάρχει προηγούμενο βήμα. διαφορετικά, false.
goToNextStep	void	Μεταβαίνει στο επόμενο βήμα. Υποβάλλει τη φόρμα εάν δεν υπάρχει επόμενο βήμα.
goToPreviousStep	void	Μεταβαίνει στο προηγούμενο βήμα. Δημιουργεί μια εξαίρεση εάν δεν υπάρχει καμία.

Παράδειγμα φόρμας πολλών βημάτων

Αυτό το παράδειγμα δείχνει πώς μπορείτε να ανακτήσετε μια φόρμα πολλαπλών βημάτων, να την εξετάσετε και να προχωρήσετε στο επόμενο βήμα.

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();  

Καρτέλα

Η A Tab περιέχει μία ή περισσότερες ενότητες μέσα σε μια φόρμα.

Ιδιότητα Tab Sections

Ένας πίνακας ενοτήτων μέσα στην καρτέλα.

Μέθοδοι tab

Χρησιμοποιήστε αυτές τις μεθόδους για να ελέγξετε την ορατότητα μιας καρτέλας, να ανακτήσετε το όνομά της και να αλλάσετε εάν είναι ορατή.

Μέθοδος	Επιστροφές	Περιγραφή
getVisible	boolean	Επιστρέφει την τιμή true εάν η καρτέλα είναι ορατή. διαφορετικά, false.
getName	string	Επιστρέφει το όνομα της καρτέλας.
setVisible(isVisible: boolean)	void	Ορίζει την ορατότητα της καρτέλας.

Παράδειγμα καρτέλας

Αυτό το παράδειγμα ανακτά μια φόρμα, απαριθμεί τις καρτέλες της και καταγράφει το όνομα της πρώτης καρτέλας.

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

Στοιχεία ελέγχου ομάδας ενοτήτων μέσα σε μια καρτέλα.

Ιδιότητα ενότητας Controls

Ένας πίνακας στοιχείων ελέγχου εντός της ενότητας.

Μέθοδοι ενότητας

Χρησιμοποιήστε αυτές τις μεθόδους για να διαβάσετε το όνομα μιας ενότητας και να ελέγξετε την ορατότητά της.

Μέθοδος	Επιστροφές	Περιγραφή
getVisible	boolean	Επιστρέφει την τιμή true εάν η ενότητα είναι ορατή. διαφορετικά, false.
getName	string	Επιστρέφει το όνομα της ενότητας.
setVisible(isVisible: boolean)	void	Ορίζει την ορατότητα της ενότητας.

Παράδειγμα ενότητας

Αυτό το παράδειγμα ανακτά ενότητες από την πρώτη καρτέλα μιας φόρμας και καταγράφει βασικές λεπτομέρειες.

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()}`);

Έλεγχος

Τα στοιχεία ελέγχου αντιπροσωπεύουν μεμονωμένα στοιχεία φόρμας.

Μέθοδοι ελέγχου

Χρησιμοποιήστε αυτές τις μεθόδους για να ανακτήσετε ή να ενημερώσετε την τιμή, την ορατότητα και την κατάσταση απενεργοποίησης ενός στοιχείου ελέγχου.

Μέθοδος	Επιστροφές	Περιγραφή
getDisabled	boolean	Επιστρέφει την τιμή true εάν το στοιχείο ελέγχου είναι απενεργοποιημένο.
getVisible	boolean	Επιστρέφει την τιμή true εάν το στοιχείο ελέγχου είναι ορατό.
getName	string	Επιστρέφει το όνομα του στοιχείου ελέγχου.
getValue	string | undefined	Ανακτά την τρέχουσα τιμή.
setDisabled(isDisabled: boolean)	void	Ορίζει την απενεργοποιημένη κατάσταση.
setVisible(isVisible: boolean)	void	Ορίζει την ορατότητα.
setValue(value: string)	void	Ορίζει μια νέα τιμή για το στοιχείο ελέγχου.

Παράδειγμα στοιχείου ελέγχου

Αυτό το παράδειγμα λαμβάνει μια φόρμα, ελέγχει την ορατότητα του πρώτου στοιχείου ελέγχου και, στη συνέχεια, την αποκρύπτει.

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

Υποστηριζόμενα στοιχεία ελέγχου

Όλα τα στοιχεία ελέγχου εφαρμόζουν τις τυπικές μεθόδους ελέγχου. Ορισμένα στοιχεία ελέγχου παρέχουν περισσότερες μεθόδους και έχουν διαφορετικές λεπτομέρειες υλοποίησης από τις τυπικές μεθόδους ελέγχου. Μάθετε σχετικά με άλλες μεθόδους και διαφορές υλοποίησης για διαφορετικούς τύπους στοιχείων ελέγχου.

$pages.currentPage.lists collection

Η συλλογή λιστών παρέχει μεθόδους για να εργαστείτε με παραδοσιακά και σύγχρονα στοιχεία λίστας στη σελίδα.

$pages.currentPage.παραθέτει μεθόδους

Χρησιμοποιήστε αυτές τις μεθόδους για να απαριθμήσετε όλες τις λίστες στη σελίδα και να λάβετε μια συγκεκριμένη λίστα με βάση το αναγνωριστικό στοιχείου HTML.

Μέθοδος	Επιστροφές	Περιγραφή
getAll	IList[]	Επιστρέφει όλες τις λίστες στην τρέχουσα σελίδα.
getListById(id: string)	IList	Λαμβάνει μια λίστα βάσει του αναγνωριστικού στοιχείου HTML.

$pages.currentPage.παραθέτει παραδείγματα

Αυτά τα παραδείγματα δείχνουν πώς μπορείτε να απαριθμήσετε όλες τις λίστες στη σελίδα και να λάβετε μια συγκεκριμένη λίστα με βάση το αναγνωριστικό στοιχείου HTML.

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

Διασύνδεση IList

Μια λίστα αντιπροσωπεύει ένα στοιχείο δεδομένων σε μορφή πίνακα ή πλέγματος.

Ιδιότητες IList

Αυτές οι ιδιότητες προσδιορίζουν τη λίστα και υποδεικνύουν εάν χρησιμοποιεί το μοντέλο σύγχρονης απόδοσης.

Property	Τύπος	Περιγραφή
id	συμβολοσειρά	Το μοναδικό αναγνωριστικό της λίστας.
isModern	δυαδική τιμή	Μια δυαδική τιμή που είναι true για σύγχρονες λίστες και false σε διαφορετική περίπτωση.

Μέθοδοι IList

Χρησιμοποιήστε αυτές τις μεθόδους για να ελέγξετε την ορατότητα της λίστας, να αλλάξτε την ορατότητα και να αποκτήσετε πρόσβαση στο υποκείμενο στοιχείο HTML.

Μέθοδος	Επιστροφές	Περιγραφή
getVisible	boolean	Επιστρέφει την τιμή true εάν η λίστα είναι ορατή.
setVisible(isVisible: boolean)	void	Ορίζει την ορατότητα της λίστας.
getHtmlElement	HTMLElement	Επιστρέφει το υποκείμενο στοιχείο HTML για τη λίστα.

Παράδειγμα IList

Το παρακάτω παράδειγμα ανακτά μια λίστα βάσει αναγνωριστικού και καταγράφει την κατάσταση ορατότητάς της.

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

Αντικείμενο $pages.user

Το $pages.user αντικείμενο παρέχει μεθόδους για την είσοδο ή την έξοδο του χρήστη.

Μέθοδοι $pages.user

Αυτές οι μέθοδοι δεν επιστρέφουν καμία τιμή.

Μέθοδος	Περιγραφή
signIn	Ανακατευθύνει το χρήστη στη σελίδα εισόδου.
signOut	Εξέρχεται από τον χρήστη που έχει εισέλθει τη συγκεκριμένη στιγμή.

Αντικείμενο $pages.webAPI

Το $pages.webAPI αντικείμενο παρέχει μεθόδους για τη δημιουργία και την ανάκτηση εγγραφών από μια προέλευση δεδομένων.

μέθοδος createRecord

Δημιουργεί μια νέα εγγραφή στον καθορισμένο πίνακα.

Σύνταξη: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<object>
Επιστρέφει: Μια υπόσχεση που επιλύθηκε στο αποτέλεσμα εγγραφής ή λειτουργίας που δημιουργήθηκε.

παράμετροι μεθόδου createRecord

Εισαγάγετε τον πίνακα προορισμού και το αντικείμενο δεδομένων που αντιπροσωπεύει την εγγραφή που θα δημιουργηθεί.

Παράμετρος	Τύπος	Περιγραφή
entitySetName	συμβολοσειρά	Το όνομα του συνόλου οντοτήτων. Μάθετε σχετικά με το όνομα του συνόλου οντοτήτων στο API Web του Dataverse
data	αντικείμενο	Τα δεδομένα εγγραφής που θα δημιουργηθούν.

παράδειγμα μεθόδου createRecord

Αυτό το παράδειγμα παρουσιάζει την κλήση createRecord με ένα όνομα συνόλου οντοτήτων και ένα ελάχιστο αντικείμενο δεδομένων.

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

μέθοδος retrieveRecord

Ανακτά μια εγγραφή με το μοναδικό της αναγνωριστικό.

Σύνταξη: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Επιστρέφει: Μια υπόσχεση που επιλύθηκε στο αντικείμενο εγγραφής.

retrieveRecord method parameters

Καθορίστε τον πίνακα, το αναγνωριστικό εγγραφής και τις προαιρετικές επιλογές ερωτήματος OData $select για να διαμορφώσετε την απόκριση.

Παράμετρος	Τύπος	Περιγραφή
entitySetName	συμβολοσειρά	Το όνομα του συνόλου οντοτήτων. Μάθετε σχετικά με το όνομα του συνόλου οντοτήτων στο API Web του Dataverse.
id	συμβολοσειρά	Το μοναδικό αναγνωριστικό της εγγραφής.
options	συμβολοσειρά (προαιρετικό)	Μια προαιρετική συμβολοσειρά ερωτήματος OData $select για τον περιορισμό των δεδομένων που επιστρέφονται.

Note

Παρόλο που η παράμετρος options είναι προαιρετική, για καλύτερες επιδόσεις περιορίστε πάντα τον αριθμό των τιμών στήλης που επιστρέφονται χρησιμοποιώντας την $select επιλογή.

παράδειγμα μεθόδου retrieveRecord

Αυτό το παράδειγμα ανακτά μια μοναδική εγγραφή κατά αναγνωριστικό και περιορίζει τις στήλες που επιστρέφονται χρησιμοποιώντας μια επιλογή ερωτήματος OData $select .

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

μέθοδος retrieveMultipleRecords

Ανακτά πολλαπλές εγγραφές με βάση τις επιλογές ερωτήματος που παρέχονται.

Σύνταξη: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Επιστρέφει: Μια υπόσχεση που επιλύει σε έναν πίνακα αντικειμένων εγγραφής.

παράμετροι μεθόδου retrieveMultipleRecords

Καθορίστε τον πίνακα και προαιρετικά το ερώτημα OData για να φιλτράρετε τα αποτελέσματα και να περιορίσετε τις στήλες που επιστρέφονται.

Παράμετρος	Τύπος	Περιγραφή
entitySetName	συμβολοσειρά	Το όνομα του συνόλου οντοτήτων.
options	συμβολοσειρά (προαιρετικό)	Μια συμβολοσειρά επιλογών ερωτήματος OData για τον έλεγχο των δεδομένων που επιστρέφονται. Μάθετε περισσότερα σχετικά με τις επιλογές ερωτήματος OData που υποστηρίζονται από το Dataverse Web API

Note

Παρόλο που η παράμετρος options είναι προαιρετική, για καλύτερες επιδόσεις περιορίστε πάντα τον αριθμό των τιμών στήλης που επιστρέφονται χρησιμοποιώντας την $select επιλογή.

παράδειγμα μεθόδου retrieveMultipleRecords

Αυτό το παράδειγμα ανακτά πολλαπλές εγγραφές και χρησιμοποιεί OData $select και $top για να περιορίσει το πλήθος των στηλών και των γραμμών που επιστρέφονται.

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

$pages.languages

Το $pages.languages αντικείμενο παρέχει μεθόδους για την ανάκτηση της λίστας των διαθέσιμων γλωσσών για την τοποθεσία Web, τη λήψη της τρέχουσας ενεργής γλώσσας και τον ορισμό μιας νέας ενεργής γλώσσας.

μέθοδοι $pages.languages

Χρησιμοποιήστε αυτές τις μεθόδους για να διαβάσετε τις διαθέσιμες γλώσσες, να ελέγξετε την τρέχουσα γλώσσα και να την αλλάξετε για την τοποθεσία.

Μέθοδος	Περιγραφή	Επιστροφές
getAll	Επιστρέφει τη λίστα των γλωσσών που είναι ενεργοποιημένες για την τοποθεσία Web.	string[]
getActive	Ανακτά την τρέχουσα ενεργή γλώσσα.	string
setActive(language: string)	Ορίζει τη δεδομένη γλώσσα ως ενεργή γλώσσα.	void

Note

setActive Η μέθοδος προκαλεί επανάληψη φόρτωσης σελίδας.

Παραδείγματα μεθόδου $pages.languages

Αυτά τα παραδείγματα δείχνουν πώς μπορείτε να παρατίθενται όλες οι γλώσσες, να διαβάζετε την ενεργή γλώσσα και να ορίζετε μια νέα ενεργή γλώσσα.

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

$pages.agent

Το αντικείμενο $pages.agent παρέχει μεθόδους για τη δημιουργία επικοινωνίας μεταξύ της τοποθεσίας και του Microsoft Copilot Studio παράγοντα που είναι διαθέσιμος στον τρέχοντα χρήστη.

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);

Όνομα παραμέτρου	Τύπος	Περιγραφή
agentSchemaName	String	Όνομα σχήματος του bot στο οποίο αποστέλλεται η δραστηριότητα.
inputActivity	Αντικείμενο	Αντικείμενο που περιέχει το κείμενο ή το συμβάν για αποστολή στο bot.
responseSubscriber	λειτουργία	Συνάρτηση επιστροφής κλήσης που εκτελείται όταν ο παράγοντας στέλνει μια απόκριση.
errorSubscriber	λειτουργία	Συνάρτηση επιστροφής κλήσης που χειρίζεται σφάλματα.

Τύπος επιστροφής: void - Η συνάρτηση δεν επιστρέφει τίποτα.

Αντικείμενο απόκρισης από τον παράγοντα που λήφθηκε με την ακόλουθη μορφή:

Πλήρες όνομα	Τύπος	Περιγραφή
type	String	Τύπος της δραστηριότητας, όπως μήνυμα.
text	String	Προαιρετικό, μήνυμα από τον παράγοντα.
textFormat	String	Προαιρετικό, μορφή του κειμένου του μηνύματος, όπως markdown, απλό ή XML.
Id	String	Αναγνωριστικό που προσδιορίζει με μοναδικό τρόπο τη δραστηριότητα.
From	Αντικείμενο	Καθορίζει τον αποστολέα της δραστηριότητας (περιλαμβάνει το αναγνωριστικό, το όνομα (προαιρετικό) και τις πληροφορίες ρόλου.
Conversation	Αντικείμενο	Περιέχει το αναγνωριστικό της συνομιλίας στην οποία ανήκει η δραστηριότητα.
InputHint	String	Προαιρετικό, υποδεικνύει εάν το bot δέχεται, αναμένει ή παραβλέπει τα δεδομένα εισόδου χρήστη.
replyToId	String	Το αναγνωριστικό του μηνύματος απάντησης.

Παράδειγμα

Μέθοδος επιστροφής κλήσης

Καθορίστε τις συναρτήσεις επιστροφής responseSubscriber κλήσης και errorSubscriber για τον χειρισμό αποκρίσεων και σφαλμάτων παράγοντα.

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';  

Αποστολή μηνύματος στον πράκτορα

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

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

Κλήση συμβάντος προγράμματος-πελάτη

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

Μηνύματα σφάλματος

Ακολουθούν πιθανά μηνύματα σφάλματος που μπορούν να αντιμετωπίσουν οι χρήστες και οι πιθανές αιτίες τους.

Τύπος σφάλματος	Αιτία	Μήνυμα σφάλματος για τον χρήστη
Επικύρωση σχήματος παράγοντα	Παρέχεται μη έγκυρο όνομα σχήματος bot ή ο χρήστης δεν έχει δικαιώματα πρόσβασης στον παράγοντα	Invalid bot schema name or access denied. Please check the bot schema name and try again.
Σφάλμα διακριτικού ανάκτησης	Παρουσιάστηκε σφάλμα κατά τη λήψη του διακριτικού απευθείας γραμμής	Something went wrong while fetching the token. Please try again.
Μήνυμα σφάλματος δραστηριότητας (επανάληψη)	Παρουσιάστηκε σφάλμα κατά την καταχώρηση της δραστηριότητας και απαιτείται επανάληψη.	Something went wrong while posting the activity: retry.
Μήνυμα σφάλματος δραστηριότητας (χρονικό όριο)	Χρονικό όριο κατά την αναμονή για εξερχόμενο μήνυμα ή postActivity	Timed out while posting activity: Please retry.
Μήνυμα σφάλματος δραστηριότητας (μη έγκυρη δραστηριότητα)	Η δραστηριότητα εισόδου δεν διαθέτει κείμενο ή όνομα για την κλήση του συμβάντος.	Invalid activity: At least one of text, name, or attachments must be provided.
Μήνυμα σφάλματος δραστηριότητας (το αναγνωριστικό χρήστη δεν βρέθηκε ή το διακριτικό δεν βρέθηκε)	Το διακριτικό δεν βρέθηκε στον χώρο αποθήκευσης περιόδου λειτουργίας ή το αναγνωριστικό χρήστη δεν βρέθηκε στο διακριτικό	Error retrieving user ID: {error message}
Μήνυμα σφάλματος δραστηριότητας (γενικά)	Παρουσιάστηκε ένα μη καθορισμένο σφάλμα κατά την καταχώρηση της δραστηριότητας	Something went wrong while posting the activity: Please try again.
Σφάλμα σύνδεσης απευθείας γραμμής	Παρουσιάστηκε σφάλμα κατά τη δημιουργία απευθείας σύνδεσης γραμμής με το bot.	Something went wrong while creating direct line connection: Please try again.
Γενικό σφάλμα	Ένα μη αναμενόμενο σφάλμα που δεν εμπίπτει στις παραπάνω κατηγορίες	An unexpected error occurred while sending activity: Please try again.