Web API を使用したエンティティの更新と削除

[アーティクル]
10/31/2017

公開日: 2017年1月

対象: Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

データを変更する操作は Web API のコア部分です。単純な更新と削除に加えて、単一の属性に対して操作を実行して、エンティティの有無に基づいてそのエンティティを更新または挿入する upsert 要求を作成できます。

注意

エンティティを定義するメタデータは別の形式で更新されます。詳細:Web API を使用してエンティティ定義を作成および更新

このトピックの内容

基本的な更新

返されるデータでの更新

単一のプロパティ値の更新

単一のプロパティ値の削除

エンティティの Upsert

基本的な削除

基本的な更新

更新操作には、HTTP PATCH 動詞を使用します。更新するプロパティが含まれる JSON オブジェクトを、エンティティを表す URI に渡します。更新が成功した場合、状態 204 の応答が返されます。

この例は、accountid 値 00000000-0000-0000-0000-000000000001 で既存の取引先企業レコードを更新します。

重要

エンティティを更新するとき、要求本文には変更するプロパティのみを含めます。先に取得したエンティティのプロパティを単純に更新して、その JSON を要求に含めることにより、値が同じであっても、各プロパティが更新されます。これにより、プロパティが実際に変更されなかったとき、監査データではプロパティが更新されたように見えます。

要求

PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

応答

HTTP/1.1 204 No Content
OData-Version: 4.0

注意

更新時のエンティティの関連付けについては、更新時にエンティティを関連付けるを参照してください。

返されるデータでの更新

注意

この機能は Dynamics 365 用 2016 年 12 月の更新プログラム (オンラインおよび設置型) を使用して追加されました。

更新するエンティティからデータを取得するには、PATCH 要求を作成して、作成されたレコードからのデータを 200 (OK) の状態で返すことができます。結果を取得するには、要求のヘッダーで return=representation の基本設定を使用する必要があります。

どのプロパティが返されるかを制御するには、$select クエリオプションを URL に、そしてエンティティセットに追加します。$expand クエリオプションは、使用すると無視されます。

この例では、取引先企業エンティティを更新し、応答で必要なデータを返します。

要求

PATCH cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{"name":"Updated Sample Account"}

応答

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts/$entity",
    "@odata.etag": "W/\"536537\"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2016-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

単一のプロパティ値の更新

単一のプロパティ値のみを更新するときは、エンティティのUri にプロパティ名が付加された PUT 要求を使用します。

次の例は、accountid 値 00000000-0000-0000-0000-000000000001 で既存の取引先企業エンティティの name プロパティを更新します。

要求

PUT cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

応答

HTTP/1.1 204 No Content
OData-Version: 4.0

単一のプロパティ値の削除

単一のプロパティ値を削除するには、エンティティの Uri にプロパティ名が付加された DELETE 要求を使用します。

次の例は、accountid 値 00000000-0000-0000-0000-000000000001 で取引先企業エンティティの description プロパティの値を削除します。

要求

DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/description HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

応答

HTTP/1.1 204 No Content
OData-Version: 4.0

注意

これを単一値のナビゲーションプロパティに対して使用して、2 つのエンティティの関連付けを解除することはできません。代替の方法については、エンティティへの参照の削除を参照してください。

エンティティの Upsert

upsert 操作は更新とよく似ています。この操作では PATCH 要求が使用され、 URI を使用して特定のエンティティが参照されます。違いは、エンティティが存在しない場合にエンティティが作成されることです。すでに存在する場合は、そのエンティティが更新されます。通常、新しいエンティティの作成時に、システムが一意の識別子を割り当てるようにすることができます。これがベストプラクティスです。特定の id 値でレコードを作成する必要がある場合は、upsert がこれを行う方法を提供します。これは、異なるシステムのデータを同期している状態で有益なことがあります。

upsert を操作する場合もありますが、既定である可能性のあるアクションである、作成または更新のいずれかを止める方がいいでしょう。If-Match または If-None-Match の追加によってこれを実行できます。詳細については、「upsert 操作の制限」を参照してください。

基本的な削除

削除操作は非常に単純です。削除するエンティティの URI に対して、DELETE 動詞を使用します。この例のメッセージは、主キーの accountid 値が00000000-0000-0000-0000-000000000001 に等しい取引先企業エンティティを削除します。

要求

DELETE cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

応答
このエンティティが存在する場合は、削除に成功したことを示す状態が 204 の通常応答を受け取ります。エンティティが存在しなかった場合は、状態が 404 の応答を受け取ります。
```
HTTP/1.1 204 No Content
OData-Version: 4.0
```

次の方法で共有

Web API を使用したエンティティの更新と削除

このトピックの内容

基本的な更新

返されるデータでの更新

単一のプロパティ値の更新

単一のプロパティ値の削除

エンティティの Upsert

基本的な削除

関連項目

その他のリソース