使用门户 Web API 写入、更新和删除操作
备注
从 2022 年 10 月 12 日起，Power Apps 门户更名为 Power Pages。 详细信息请参阅：Microsoft Power Pages 现已正式发布（博客）
不久后我们将迁移 Power Apps 门户文档并将其与 Power Pages 文档合并在一起。
您可以在门户中执行可用的 WEB API 操作。 Web API 操作包含 HTTP 请求和响应。 本文提供了您可以在 HTTP 请求中使用的示例写入、更新和删除操作、方法、URI 和示例 JSON。
重要
- 您的门户版本必须为 9.3.3.x 或更高版本才能使用此功能。
先决条件
为 Web API 操作启用表和字段。 详细信息：Web API 的站点设置
门户 Web API 访问表记录，并遵循通过关联的 Web 角色授予用户的表权限。 请确保配置正确的表权限。 详细信息：创建 Web 角色
在表中创建记录
备注
使用门户 Web API 引用 Dataverse 表时，需要使用 EntitySetName，例如，访问客户表，代码语法将使用客户的 EntitySetName。
基本创建
| 操作 | 方法 | URI | JSON 示例 |
|---|---|---|---|
| 基本创建 | 公告 | [门户 URI]/_api/accounts | {"名称":"示例客户"} |
用于在一次操作中创建相关表记录的示例 JSON
例如，发布到客户表集的以下请求正文将在创建客户的上下文中创建总计四个新表—包括客户。
- 创建联系人是因为它被定义为单值导航属性
primarycontactid的对象属性。 - 创建商机是因为它被定义为数组中设置为集合值导航属性
opportunity_customer_accounts的值的对象。 - 创建任务是因为它被定义为数组中设置为集合值导航属性
Opportunity_Tasks的值的对象。
{
"name": "Sample Account",
"primarycontactid":
{
"firstname": "Alton",
"lastname": "Stott"
},
"opportunity_customer_accounts":
[
{
"name": "Opportunity associated to Sample Account",
"Opportunity_Tasks":
[
{ "subject": "Task associated to opportunity" }
]
}
]
}
创建时关联表记录
| Operation | Method | URI | JSON 示例 |
|---|---|---|---|
| 创建时关联表记录 | POST | [门户 URI]/_api/accounts | {"name":"Sample Account","primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"} |
用于通过 Web API 创建注释的示例 JSON
{
"new_attribute1": "test attribute 1",
"new_attribute2": "test attribute 2",
"new_comments": "test comments",
"new_recordurl": recordURL,
"new_feedback_Annotations":
[
{
"notetext": "Screenshot attached",
"subject": "Attachment",
"filename": file.name,
"mimetype": file.type,
"documentbody": base64str,
}
]
}
documentbody 将包含 base64 字符串形式的附件。
使用 Web API 更新和删除记录
基本更新
| 操作 | 方法 | URI | JSON 示例 |
|---|---|---|---|
| 基本更新 | PATCH | [门户 URI]/_api/accounts(00000000-0000-0000-0000-000000000001) | { "name": "Updated Sample Account ", "creditonhold": true, "address1_latitude": 47.639583, "description": "This is the updated description of the sample account", "revenue": 6000000, "accountcategorycode": 2 } |
更新单个属性值
| 操作 | 方法 | URI | JSON 示例 |
|---|---|---|---|
| 更新单个属性值 | PUT | [门户 URI]/_api/accounts(00000000-0000-0000-0000-000000000001)/name | {"value": "Updated Sample Account Name"} |
删除或清除字段值
| Operation | Method | URI |
|---|---|---|
| 删除或清除字段值 | DELETE | [门户 URI]/_api/accounts(00000000-0000-0000-0000-000000000001)/description |
基本删除
| 操作 | 方法 | URI |
|---|---|---|
| 基本删除 | Delete | [门户 URI]/_api/accounts(00000000-0000-0000-0000-000000000001) |
使用 Web API 关联和取消关联表
添加对集合值导航属性的引用
| 操作 | 方法 | URI | JSON 示例 |
|---|---|---|---|
| 添加对集合值导航属性的引用 | 公告 | [门户 URI]/_api/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref | {"@odata.id":"[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)"} |
删除对表的引用
| 操作 | 方法 | URI |
|---|---|---|
| 删除对表的引用 | DELETE | [门户 URI]/_api/accounts(00000000-0000-0000-0000-000000000002)/opportunity_customer_accounts/$ref?$id=[Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001) |
针对单值导航属性删除对表的引用
对于单值导航属性，请删除 $id 查询字符串参数。
| 操作 | 方法 | URI |
|---|---|---|
| 针对单值导航属性删除对表的引用 | DELETE | [门户 URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref |
更改单值导航属性中的引用
| 操作 | 方法 | URI | JSON 示例 |
|---|---|---|---|
| 更改单值导航属性中的引用 | PUT | [门户 URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref | {"@odata.id":"[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)"} |
创建时关联表
使用深层插入可以创建具有关系的新表。
使用单值导航属性在更新时关联表
可以使用此主题前面的基本更新中所述的相同消息在更新时关联表，但必须使用 @odata.bind 注释设置单值导航属性的值。 以下示例使用 customerid_account 单值导航属性更改与商机关联的客户。
使用单值导航属性在更新时关联表
| 操作 | 方法 | URI | JSON 示例 |
|---|---|---|---|
| 使用单值导航属性在更新时关联表 | PATCH | [门户 URI]/_api/opportunities(00000000-0000-0000-0000-000000000001) | {"customerid_account@odata.bind":"[Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000002)"} |
Web API AJAX 示例
本示例演示如何使用异步 JavaScript 和 XML (AJAX) 创建、更新和删除表记录。
包装器 AJAX 函数
(function(webapi, $){
function safeAjax(ajaxOptions) {
var deferredAjax = $.Deferred();
shell.getTokenDeferred().done(function (token) {
// add headers for AJAX
if (!ajaxOptions.headers) {
$.extend(ajaxOptions, {
headers: {
"__RequestVerificationToken": token
}
});
} else {
ajaxOptions.headers["__RequestVerificationToken"] = token;
}
$.ajax(ajaxOptions)
.done(function(data, textStatus, jqXHR) {
validateLoginSession(data, textStatus, jqXHR, deferredAjax.resolve);
}).fail(deferredAjax.reject); //AJAX
}).fail(function () {
deferredAjax.rejectWith(this, arguments); // on token failure pass the token AJAX and args
});
return deferredAjax.promise();
}
webapi.safeAjax = safeAjax;
})(window.webapi = window.webapi || {}, jQuery)
创建
webapi.safeAjax({
type: "POST",
url: "/_api/accounts",
contentType: "application/json",
data: JSON.stringify({
"name": "Sample Account"
}),
success: function (res, status, xhr) {
//print id of newly created table record
console.log("entityID: "+ xhr.getResponseHeader("entityid"))
}
});
Update
webapi.safeAjax({
type: "PATCH",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
data: JSON.stringify({
"name": "Sample Account - Updated"
}),
success: function (res) {
console.log(res);
}
});
Delete
webapi.safeAjax({
type: "DELETE",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
contentType: "application/json",
success: function (res) {
console.log(res);
}
});