ポータル Web API を使用して、操作を書き込み、更新、および削除します
ポータルで、利用可能な WebAPI 操作 をおこなうことができます。 Web API 操作は、HTTP リクエストとレスポンスで構成されています。 この記事では、HTTP 要求で使用できるサンプルの書き込み、更新、削除の操作、メソッド、URI、サンプル JSON について説明します。
重要
- この機能を使用するには、ポータルのバージョンが 9.3.3.x 以降である必要があります。
前提条件
Web API 操作のテーブルとフィールドを有効にします。 詳細:Web API のサイト設定
ポータル Web API は、テーブル レコードにアクセスし、関連した Web ロール からユーザーに与えられたテーブルのアクセス許可に従います。 正しいテーブル アクセス許可を構成していることを確認してください。 詳細: Web ロールを作成する
テーブルでレコードを作成する
注意
ポータルの Web API を使用して Dataverse テーブルを参照する場合、EntitySetName を使用する必要があります。例えば、account テーブルにアクセスする場合、コード構文では アカウント の EntitySetName が使用されます。
基本的な作成
| オペレーション | 方法 | URI | JSON サンプル |
|---|---|---|---|
| 基本的な作成 | POST | [Portal URI]/_api/accounts | {"name":"Sample Account"} |
1 回の操作で関連するテーブル レコードを作成するための JSON サンプル
例として、アカウント テーブル セットに投稿された次の要求本文は、アカウントを作成する場合に、アカウントを含む合計 4 つの新しいテーブルを作成します。
- 連絡先が作成されたのは、単一値のナビゲーション プロパティ
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 | メソッド | URI | JSON サンプル |
|---|---|---|---|
| 作成時にテーブルレコードを関連付ける | POST | [Portal URI]/_api/accounts | {"name":"Sample Account","primarycontactid@odata.bind":"/contacts(00000000-0000-0000-0000-000000000001)"} |
WebAPI を介して注釈を作成するためのサンプル 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 | [Portal 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 | [Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000001)/name | {"value": "Updated Sample Account Name"} |
フィールド値の削除またはクリア
| オペレーション | メソッド | URI |
|---|---|---|
| フィールド値の削除またはクリア | DELETE | [Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000001)/description |
基本的な削除
| 操作 | メソッド | URI |
|---|---|---|
| 基本的な削除 | DELETE | [Portal URI]/_api/accounts(00000000-0000-0000-0000-000000000001) |
Web API を使用したテーブルの関連付けと関連付け解除
コレクション値ナビゲーション プロパティへの参照の追加
| 操作 | メソッド | URI | JSON サンプル |
|---|---|---|---|
| コレクション値ナビゲーション プロパティへの参照の追加 | 投稿 | [Portal 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 | [Portal 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 | [Portal URI]/_api/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref |
単一値ナビゲーション プロパティでの参照の変更
| 操作 | メソッド | URI | JSON サンプル |
|---|---|---|---|
| 単一値ナビゲーション プロパティでの参照の変更 | PUT | [Portal 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 | [Portal 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)
Create
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"))
}
});
更新する
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);
}
});
関連付け
次の例では、既存の取引先企業の取引先担当者を取引先責任者として割り当てます。
var record = {};
record[primarycontactid@odata.bind] = "/contacts(00000000-0000-0000-0000-000000000002)";
webapi.safeAjax({
type: "PATCH",
contentType: "application/json",
url: "/_api/accounts(00000000-0000-0000-0000-000000000001)",
data: JSON.stringify(record),
success: function (data, textStatus, xhr) {
console.log("Record updated");
}
});