Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Este ejemplo contiene código que muestra cómo realizar operaciones básicas CRUD (Crear, Recuperar, Actualizar y Eliminar) y de asociación y disociación en filas de tablas (registros de entidades) usando JavaScript de lado de cliente. Este ejemplo completa el conjunto de operaciones descritas en el Ejemplo de Operaciones Básicas de la API Web.
Este código usa la biblioteca de ejemplo DataverseWebAPI.js y está diseñado para ejecutarse en el contexto de un ejemplo de una aplicación de una sola página (SPA) disponible en GitHub. Más información acerca de la aplicación de ejemplo
Nota
Este código es para una aplicación de una sola página (SPA) y no representa el patrón que se usará con aplicaciones basadas en modelo, componentes de Power Apps components framework (PCF) o Power Pages. Use Xrm.WebApi (API de cliente), componentes de código de API web y Power Pages Portals API Web para estos escenarios.
Requisitos previos
Este ejemplo tiene los mismos requisitos previos que Inicio rápido de API web con JavaScript del lado del cliente y Visual Studio Code. Para ejecutar este ejemplo, primero debe completar el inicio rápido. Puede usar la misma información de registro de la aplicación para ese inicio rápido para ejecutar este ejemplo.
Context
Este ejemplo comienza cuando el usuario selecciona un botón que desencadena el siguiente controlador de eventos:
// Add event listener to the basic operations button
document.getElementById("basicOperationsButton").onclick = async function () {
runSample(new BasicOperationsSample(client, container));
};
La función runSample toma una instancia de la clase BasicOperationsSample en la que el constructor acepta una instancia de DataverseWebAPI.Client y una referencia a un contenedor en el que escribir mensajes.
// Runs all samples in a consistent way
async function runSample(sample) {
// Disable the buttons to prevent multiple clicks
document.getElementsByTagName("nav")[0].classList.add("disabled");
// Disable the logout button while the sample is running
logoutButton.classList.add("disabled");
// Run the sample
await sample.SetUp();
await sample.Run();
await sample.CleanUp();
// Re-enable the buttons
document.getElementsByTagName("nav")[0].classList.remove("disabled");
logoutButton.classList.remove("disabled");
}
BasicOperationsSample.js
A continuación se muestra la clase BasicOperationsSample que contiene el código de este ejemplo.
import { Util } from "../scripts/Util.js";
import { DataverseWebAPI as dv } from "../scripts/DataverseWebAPI.js";
export class BasicOperationsSample {
/**
* @type {dv.Client}
* @private
*/
#client; // The DataverseWebAPIClient.Client instance
#container; // The container element to display messages
#entityStore = []; // Store for created records to delete at the end of the sample
#whoIAm; // Store for the current user's information
#util; // Util instance for utility functions
#name = "Basic Operations";
// Constructor to initialize the client, container, and utility helper functions
constructor(client, container) {
this.#client = client;
this.#container = container;
this.#util = new Util(container);
}
// Public functions to set up, run, and clean up data created by the sample
async SetUp() {
// Clear the container
this.#container.replaceChildren();
this.#util.appendMessage(this.#name + " sample started");
// Get the current user's information
try {
this.#whoIAm = await this.#client.WhoAmI();
} catch (error) {
this.#util.showError(error.message);
}
}
// Run the sample
async Run() {
try {
// Section 1: Basic create and update operations
this.#util.appendMessage(
"<h2>1: Basic create and update operations</h2>"
);
const rafelShilloId = await this.#createContact();
await this.#updateContact(rafelShilloId);
await this.#retrieveContact(rafelShilloId);
await this.#updateContactAgain(rafelShilloId);
await this.#retrieveContact(rafelShilloId);
await this.#setPhoneNumber(rafelShilloId);
await this.#getPhoneNumber(rafelShilloId);
// Section 2: Create with association
this.#util.appendMessage("<h2>2: Create with association</h2>");
const contosoAccountId = await this.#createWithAssociation(rafelShilloId);
await this.#retrievePrimaryContactFromAccount(contosoAccountId);
// Section 3: Create related table rows (deep insert)
this.#util.appendMessage(
"<h2>3: Create related table rows (deep insert)</h2>"
);
const fourthCoffeeId = await this.#createRelatedTableRows();
const susieCurtisId = await this.#retrieveFourthCoffeePrimaryContact(
fourthCoffeeId
);
await this.#retrieveContactRelatedTasks(susieCurtisId);
// Section 4: Associate and disassociate existing entities
this.#util.appendMessage(
"<h2>4: Associate and disassociate existing entities</h2>"
);
await this.#associateContactToAccount(fourthCoffeeId, rafelShilloId);
await this.#showRelatedContacts(fourthCoffeeId);
const roleId = await this.#createSecurityRole();
await this.#associateRoleToUser(roleId);
await this.#retrieveRelatedRole(roleId);
await this.#disassociateRoleFromUser(roleId);
} catch (error) {
this.#util.showError(error.message);
// Try to clean up even if an error occurs
await this.CleanUp();
}
}
//#region Section 1: Basic create and update operations
// Demonstrates creating a record
async #createContact() {
const contact = {
firstname: "Rafel",
lastname: "Shillo",
};
try {
const contactId = await this.#client.Create("contacts", contact);
this.#util.appendMessage(
`Created contact: ${contact.firstname} ${contact.lastname}`
);
// To delete later
this.#entityStore.push({
name: `${contact.firstname} ${contact.lastname}`,
entityName: "contact",
entitySetName: "contacts",
id: contactId,
});
return contactId;
} catch (e) {
this.#util.showError(`Failed to create contact: ${e.message}`);
throw e;
}
}
// Demonstrates updating a record
async #updateContact(contactId) {
const contact = {
annualincome: 80000,
jobtitle: "Junior Developer",
};
try {
await this.#client.Update("contacts", contactId, contact);
this.#util.appendMessage(
`Updated contact setting new job title and annual income.`
);
} catch (e) {
this.#util.showError("Failed to update contact.");
throw e;
}
}
// Demonstrates retrieving a record
async #retrieveContact(contactId) {
try {
const contact = await this.#client.Retrieve(
"contacts",
contactId,
"$select=fullname,annualincome,telephone1,jobtitle,description"
);
this.#util.appendMessage(`Retrieved contact with id: ${contactId}`);
const table = this.#util.createTable(contact);
this.#container.appendChild(table);
} catch (e) {
this.#util.showError("Failed to retrieve contact.");
throw e;
}
}
// Demonstrates updating the record again.
async #updateContactAgain(contactId) {
const contact = {
annualincome: 95000,
jobtitle: "Senior Developer",
description: "Assignment to-be-determined",
};
try {
await this.#client.Update("contacts", contactId, contact);
this.#util.appendMessage(
`Updated contact setting new job title, annual income, and description.`
);
} catch (e) {
this.#util.showError("Failed to update contact.");
throw e;
}
}
// Demonstrates setting a single value on a record
async #setPhoneNumber(contactId) {
const phoneNumber = "555-0105";
try {
await this.#client.SetValue(
"contacts",
contactId,
"telephone1",
phoneNumber
);
this.#util.appendMessage(`Set contact phone number to: ${phoneNumber}`);
} catch (e) {
this.#util.showError("Failed to update contact.");
throw e;
}
}
// Demonstrates retrieving a single value from a record
async #getPhoneNumber(contactId) {
try {
const phoneNumber = await this.#client.GetValue(
"contacts",
contactId,
"telephone1"
);
this.#util.appendMessage(
`Contact's telephone number is: ${phoneNumber}.`
);
} catch (e) {
this.#util.showError("Failed to retrieve contact phone number.");
throw e;
}
}
//#endregion Section 1: Basic create and update operations
//#region Section 2: Create with association
// Demonstrates creating a record with an association to another record
async #createWithAssociation(contactId) {
// Use the @odata.bind notation to create an account associated with an existing primary contact
const contosoAccount = {
name: "Contoso Ltd",
telephone1: "555-5555",
"primarycontactid@odata.bind": "contacts(" + contactId + ")",
};
try {
const accountId = await this.#client.Create("accounts", contosoAccount);
this.#util.appendMessage(`Created ${contosoAccount.name} account`);
this.#entityStore.push({
name: contosoAccount.name,
entityName: "account",
entitySetName: "accounts",
id: accountId,
});
return accountId;
} catch (e) {
this.#util.showError(`Failed to create account: ${e.message}`);
throw e;
}
}
// Demonstrates retrieving a record with an associated record
async #retrievePrimaryContactFromAccount(accountId) {
try {
const account = await this.#client.Retrieve(
"accounts",
accountId,
"$select=name&$expand=primarycontactid($select=fullname,jobtitle,annualincome)"
);
this.#util.appendMessage(
`Account '${account.name}' has primary contact '${account.primarycontactid.fullname}':`
);
const table = this.#util.createTable(account.primarycontactid);
this.#container.appendChild(table);
} catch (e) {
this.#util.showError("Failed to retrieve account.");
throw e;
}
}
//#endregion Section 2: Create with association
//#region Section 3: Create related table rows (deep insert)
// Demonstrates creating a record with related table rows (deep insert)
async #createRelatedTableRows() {
const fourthCoffee = {
name: "Fourth Coffee",
primarycontactid: {
firstname: "Susie",
lastname: "Curtis",
jobtitle: "Coffee Master",
annualincome: 48000,
Contact_Tasks: [
{
subject: "Sign invoice",
description: "Invoice #12321",
scheduledstart: new Date(Date.UTC(2025, 3, 18, 20)),
scheduledend: new Date(Date.UTC(2025, 3, 18, 21)),
scheduleddurationminutes: 60,
},
{
subject: "Setup new display",
description: "Theme is - Spring is in the air",
scheduledstart: new Date(Date.UTC(2025, 4, 18, 20)),
scheduledend: new Date(Date.UTC(2025, 4, 18, 21)),
scheduleddurationminutes: 60,
},
{
subject: "Conduct training",
description: "Train team on making our new blended coffee",
scheduledstart: new Date(Date.UTC(2025, 4, 21, 20)),
scheduledend: new Date(Date.UTC(2025, 4, 21, 21)),
scheduleddurationminutes: 60,
},
],
},
};
try {
const accountId = await this.#client.Create("accounts", fourthCoffee);
this.#util.appendMessage(`Account '${fourthCoffee.name}' created.`);
this.#entityStore.push({
name: fourthCoffee.name,
entityName: "account",
entitySetName: "accounts",
id: accountId,
});
return accountId;
} catch (e) {
this.#util.showError(
`Failed to create account '${fourthCoffee.name}' : ${e.message}.`
);
throw e;
}
}
// Demonstrates retrieving a record with related table rows
async #retrieveFourthCoffeePrimaryContact(fourthCoffeeId) {
try {
const account = await this.#client.Retrieve(
"accounts",
fourthCoffeeId,
"$select=name&$expand=primarycontactid($select=fullname,jobtitle,annualincome)"
);
this.#util.appendMessage(
`Account '${account.name}' has primary contact '${account.primarycontactid.fullname}':`
);
const table = this.#util.createTable(account.primarycontactid);
this.#container.appendChild(table);
return account.primarycontactid.contactid;
} catch (e) {
this.#util.showError(`Failed to retrieve account: ${e.message}`);
throw e;
}
}
// Demonstrates retrieving a record with related table rows
async #retrieveContactRelatedTasks(contactId) {
try {
const contact = await this.#client.Retrieve(
"contacts",
contactId,
"$select=fullname&$expand=Contact_Tasks($select=subject,description,scheduledstart,scheduledend)"
);
this.#util.appendMessage(
`Contact has ${contact.Contact_Tasks.length} related tasks:`
);
let taskList = document.createElement("ul");
for (const task of contact.Contact_Tasks) {
const taskItem = this.#util.appendMessage(
`Task: ${task.subject}`,
taskList,
"li"
);
const table = this.#util.createTable(task);
taskItem.appendChild(table);
}
this.#container.appendChild(taskList);
} catch (e) {
this.#util.showError(
`Failed to retrieve contact with related tasks: ${e.message}`
);
throw e;
}
}
//#endregion Section 3: Create related table rows (deep insert)
//#region Section 4: Associate and disassociate existing entities
async #associateContactToAccount(accountId, contactId) {
try {
await this.#client.Associate(
"accounts",
accountId,
"contact_customer_accounts",
"contacts",
contactId
);
this.#util.appendMessage(
"Associated contact Rafel Shillo to account Contoso Ltd."
);
} catch (e) {
this.#util.showError(
`Failed to associate contact with id: ${contactId} to account with id: ${accountId}: ${e.message}`
);
throw e;
}
}
// Demonstrates retrieving related records
async #showRelatedContacts(accountId) {
try {
const contacts = await this.#client.RetrieveMultiple(
"accounts(" + accountId + ")/contact_customer_accounts",
"$select=fullname,jobtitle"
);
this.#util.appendMessage(
`Account has ${contacts.value.length} related contacts:`
);
let contactList = document.createElement("ul");
for (const contact of contacts.value) {
const contactItem = this.#util.appendMessage(
`Name: ${contact.fullname}`,
contactList,
"li"
);
const table = this.#util.createTable(contact);
contactItem.appendChild(table);
}
this.#container.appendChild(contactList);
} catch (e) {
this.#util.showError(`Failed to retrieve related contacts: ${e.message}`);
throw e;
}
}
async #createSecurityRole() {
const role = {
name: "Example Security Role",
"businessunitid@odata.bind": `businessunits(${
this.#whoIAm.BusinessUnitId
})`,
};
try {
const roleId = await this.#client.Create("roles", role);
this.#util.appendMessage(
`Created the ${role.name} security role with id: ${roleId}`
);
// To delete later
this.#entityStore.push({
name: role.name,
entityName: "role",
entitySetName: "roles",
id: roleId,
});
return roleId;
} catch (e) {
this.#util.showError(`Failed to create a security role: ${e.message}`);
throw e;
}
}
async #associateRoleToUser(roleId) {
try {
await this.#client.Associate(
"systemusers",
this.#whoIAm.UserId,
"systemuserroles_association",
"roles",
roleId
);
this.#util.appendMessage(
"Security Role 'Example Security Role' associated with to your user account."
);
} catch (e) {
this.#util.showError(
`Failed to associate role with id: ${roleId} to user with id: ${
this.#whoIAm.UserId
}: ${e.message}`
);
throw e;
}
}
// Verifies that the role is associated with the user
async #retrieveRelatedRole(roleId) {
try {
const roles = await this.#client.RetrieveMultiple(
`systemusers(${this.#whoIAm.UserId})/systemuserroles_association`,
`$select=name&$filter=roleid eq ${roleId}&$top=1`
);
if (roles.value.length > 0) {
this.#util.appendMessage(`Role is associated with user.`);
}
} catch (e) {
this.#util.showError(`Failed to retrieve related role: ${e.message}`);
throw e;
}
}
async #disassociateRoleFromUser(roleId) {
try {
await this.#client.Disassociate(
"systemusers",
this.#whoIAm.UserId,
"systemuserroles_association",
roleId
);
this.#util.appendMessage(
"Security Role 'Example Security Role' disassociated from your user account."
);
} catch (e) {
this.#util.showError(
`Failed to disassociate role with id: ${roleId} from user with id: ${
this.#whoIAm.UserId
}: ${e.message}`
);
throw e;
}
}
//#endregion Section 4: Associate and disassociate existing entities
// Clean up the created records
async CleanUp() {
this.#util.appendMessage("Deleting the records created by this sample");
let deleteMessageList = document.createElement("ul");
this.#container.append(deleteMessageList);
for (const item of this.#entityStore) {
try {
await this.#client.Delete(item.entitySetName, item.id);
const message = document.createElement("li");
message.textContent = `Deleted ${item.entityName} ${item.name}`;
deleteMessageList.append(message);
} catch (e) {
const message = document.createElement("li");
message.textContent = `Failed to delete ${item.entityName} ${item.name}`;
message.className = "error";
deleteMessageList.append(message);
}
}
// Set the entity store to an empty array
this.#entityStore = [];
this.#util.appendMessage(this.#name + " sample completed.");
this.#util.appendMessage("<a href='#'>Go to top</a>");
}
}
Consulte también
Usar la API web de Dataverse
Crear una fila de tabla usando la API web
Recuperar una fila de tabla usando la API web
Actualizar y eliminar filas de tablas usando la API web
Ejemplos de la API web
Ejemplo de operaciones básicas de la API web
Ejemplo de operaciones básicas de la API web (C#)
Ejemplos de la API web (JavaScript del lado del cliente)
Ejemplo de datos de consulta de la API web (JavaScript del lado del cliente)
Ejemplo de operaciones condicionales de la API web (JavaScript del lado del cliente)
Ejemplo de funciones y acciones de la API web (JavaScript del lado del cliente)