OData v2.0 エンドポイントを使用しないでください

カテゴリ: サポート可能性

影響の可能性: 高い

現象

すぐに影響はありませんが、このエンドポイントを使用するコードは非推奨のエンドポイントの廃止によって機能しなくなります。

元の削除日は 2022 年 11 月 11 日でした。 2023 年 4 月 30 日に延長されました。 ユーザーに Web API を使用するようにコードを移行する時間を与えるため、2023 年 4 月 30 日にはサービスを削除しないことを決定しました。 このエンドポイントをまだ使用している場合は、最終的な削除日が発表されたときに備えられるように、Web API を使用するコードへの移行を優先させる必要があります。 詳細情報: OData v2.0 サービス廃止日のお知らせ

ガイダンス

代わりに Dataverse Web API (OData v4.0) エンドポイントを使用するように、組織データ サービス (OData v2.0) に依存するコードを変更する必要があります。

モデル駆動型アプリの場合、JavaScript Web リソースを使用するクライアント サイド拡張機能に対応した Dataverse Web API へのアクセスを提供する、Xrm.WebApi (クライアント API 参照) を使用する必要があります。

問題となるパターン

組織データ サービスはこのエンドポイントを使用します: /XRMServices/2011/OrganizationData.svc。 このエンドポイントを使用してアクティブなコードを見つける必要があります。

Dynamics CRM SDK は sample_/Scripts/SDK.REST.js という名前の JavaScript Web リソースとしてサンプル JavaScript ライブラリを提供します。こちらからご利用ください。 Xrm.WebApi (クライアント API 参照) は、レコードの作成、更新、削除、取得を行う同様の機能を提供します。

Invoke-WebRequest を使用する PowerShell スクリプトも、組織データ サービス エンドポイント使用することがあります。

追加情報

組織データ サービスは Dynamics CRM 2011 で導入された OData v2.0 エンドポイントです。 Dynamics 365 Customer Engagement v8.0 で非推奨になりました。 リリース時には OData エンドポイントREST エンドポイントと呼ばれており、このエンドポイントはテーブルに対する作成、取得、更新、および削除の操作をサポートしています。

Dataverse Web API および組織データ サービスの両方とも OData エンドポイントですが、実装する方法は異なります。 小さな変更だけで既存のコードを機能させることは期待できません。

主な相違点のいくつかを次のセクションで説明します。

リソース名

テーブルの Web API リソース名は EntitySetName に基づきます。 組織データ サービスの名前には、SchemaNameSet が追加されていました。

Web API 組織のデータ サービス
accounts AccountSet
contacts ContactSet
タスク TaskSet

列名

Web API の列名はすべて LogicalName を使用した小文字です。 組織データ サービスでは列名に SchemaName を使用します。

HTTP メソッド

組織データ サービスは、PATCH ではなく MERGEPUT を使用してレコードを更新します。

データの書式

組織データ サービスは、JSON と、通常 RSS フィードに使用される XML ベースの形式である ATOM の両方をサポートしています。 WebAPI は JSON のみをサポートします。

返されるレコード数の制限

組織データ サービスは一度に 50 件のレコードのみを返し、最大ページ サイズを指定する方法を提供しません。

Web API では最大ページ サイズを設定でき、最大 5000 件のレコードを返します。 詳細情報: ページ結果

レガシー ドキュメント

組織データ サービスのドキュメント: Microsoft Dynamics 2015 SDK: OData エンドポイントと Web リソースを使用する

次の表は、組織データ サービスと Web API の関連領域を結び付けています。

組織のデータ サービス Web API
OData エンドポイントを使用した Microsoft Dynamics CRM 2015 データのクエリ
OData エンドポイント を使用した OData システムのクエリ オプション
クエリデータ
Web API プロパティ
レコードを作成しています テーブル行を作成する
レコードの取得 テーブル行の取得
レコードの更新 基本的な更新
レコードの削除 基本的な削除
ディープ挿入の使用 1 回の操作で関連するテーブル行を作成する
個々のプロパティの更新 単一のプロパティ値の更新
レコードの関連付けと関連付け解除 テーブル行の関連付けと関連付け解除
OData エンドポイント HTTP ステータス コード ステータス コードの確認

使用例

このセクションでは、組織データ サービスと Web API の使用の違いについて説明します。

組織データ サービスは、テーブルの作成、取得、更新、および削除の操作のみをサポートします。 次の例は、Web API への移行に役立つサービス間の違いを示しています。

レコードをクエリする

これらの例は、レコードをクエリするときの組織データ サービスと Web API の違いを示しています。

組織データ サービスには、$top および $skip を使用する以外にページングを管理する方法はありません。 最大ページ サイズは 50 レコードです。

要求:

GET  [Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode&$filter=PrimaryContactId/Id ne null&$top=2 HTTP/1.1
Accept: application/json

応答:

HTTP/1.1 200 OK
Cache-Control: no-cache
Allow: OPTIONS,GET,HEAD,POST
Content-Type: application/json;charset=utf-8

{
  "d": {
    "results": [
      {
        "__metadata": {
          "uri": " [Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'7a4814f9-b0b8-ea11-a812-000d3a122b89')",
          "type": "Microsoft.Crm.Sdk.Data.Services.Account"
        },
        "OwnershipCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": 2
        },
        "PrimaryContactId": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.EntityReference"
          },
          "Id": "dff27d1f-a61b-4bfe-a203-b2e5a36cda0e",
          "LogicalName": "contact",
          "Name": "Sam Smith",
          "RowVersion": null
        },
        "OpenDeals_Date": "/Date(1663715691000)/",
        "Telephone1": "555-1234",
        "NumberOfEmployees": 500,
        "Name": "Contoso, Ltd. (sample)",
        "AccountNumber": "1111",
        "DoNotPhone": false,
        "IndustryCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": 7
        }
      },
      {
        "__metadata": {
          "uri": " [Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'fed58509-4af3-ec11-bb3d-000d3a1a51c1')",
          "type": "Microsoft.Crm.Sdk.Data.Services.Account"
        },
        "OwnershipCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": null
        },
        "PrimaryContactId": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.EntityReference"
          },
          "Id": "ffd58509-4af3-ec11-bb3d-000d3a1a51c1",
          "LogicalName": "contact",
          "Name": "Susie Curtis",
          "RowVersion": null
        },
        "OpenDeals_Date": "/Date(1663715691000)/",
        "Telephone1": null,
        "NumberOfEmployees": null,
        "Name": "Fourth Coffee",
        "AccountNumber": null,
        "DoNotPhone": false,
        "IndustryCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": null
        }
      }
    ]
  }
}

50 を超えるレコードが返される場合は、__next プロパティを使用して次のページにアクセスします。

"__next": "https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode&$filter=PrimaryContactId/Id ne null&$skiptoken=1,'accountid','%7B22153355-851D-ED11-B83E-000D3A572421%7D','%7B7A4814F9-B0B8-EA11-A812-000D3A122B89%7D'"

レコードの作成

これらの例は、レコードを作成するときの組織データ サービスと Web API の違いを示しています。

要求:

POST [Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "OwnershipCode": {
    "Value": 2
  },
  "PrimaryContactId": {
    "Id": "dff27d1f-a61b-4bfe-a203-b2e5a36cda0e",
    "LogicalName": "contact"
  },
  "OpenDeals_Date": "12/25/2022",
  "CustomerSizeCode": {
    "Value": 1
  },
  "Telephone1": "555-1234",
  "NumberOfEmployees": 500,
  "Name": "Contoso, Ltd. (sample)",
  "AccountNumber": "12225",
  "DoNotPhone": true,
  "IndustryCode": {
    "Value": 7
  }
}

応答:

組織データ サービスでは、レコードの作成時にすべてのプロパティが返されます。

HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
REQ_ID: a0c614be-50be-4c1e-9413-1c7ba459c5c9

{
  "d": {
    "__metadata": {
      "uri": "[Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'57d4d1af-7b38-ed11-9db0-002248296d7e')",
      "type": "Microsoft.Crm.Sdk.Data.Services.Account"
    },
    "AccountId": "57d4d1af-7b38-ed11-9db0-002248296d7e",

    <All properties are returned. Removed for brevity>

  }
}

レコードの取得

これらの例は、レコードを取得するときの組織データ サービスと Web API の違いを示しています。

要求:

GET https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode HTTP/1.1
Accept: application/json

応答:

HTTP/1.1 200 OK

{
  "d": {
    "__metadata": {
      "uri": "https://[Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')",
      "type": "Microsoft.Crm.Sdk.Data.Services.Account"
    },
    "OwnershipCode": {
      "__metadata": {
        "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
      },
      "Value": 2
    },
    "PrimaryContactId": {
      "__metadata": {
        "type": "Microsoft.Crm.Sdk.Data.Services.EntityReference"
      },
      "Id": "dff27d1f-a61b-4bfe-a203-b2e5a36cda0e",
      "LogicalName": "contact",
      "Name": "Sam Smith",
      "RowVersion": null
    },
    "OpenDeals_Date": "/Date(1663784098000)/",
    "Telephone1": "555-1234",
    "NumberOfEmployees": 500,
    "Name": "Contoso, Ltd. (sample)",
    "AccountNumber": "12227",
    "DoNotPhone": true,
    "IndustryCode": {
      "__metadata": {
        "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
      },
      "Value": 7
    }
  }
}

レコードの更新

これらの例は、レコードを更新するときの組織データ サービスと Web API の違いを示しています。

組織データ サービスでは、X-HTTP-Method: MERGE 要求ヘッダーを POST 要求に適用する必要があります。

要求:

POST https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
Accept: application/json
X-HTTP-Method: MERGE
Content-Type: application/json

{
  "OwnershipCode": {
    "Value": 3
  },
  "PrimaryContactId": {
    "Id": "6db0be2e-d01c-ed11-b83e-000d3a572421"
  },
  "OpenDeals_Date": "12/26/2022",
  "Telephone1": "555-1235",
  "NumberOfEmployees": 501,
  "Name": "Contoso, Ltd.",
  "AccountNumber": "12228",
  "DoNotPhone": false,
  "IndustryCode": {
    "Value": 6
  }
}

応答:

HTTP/1.1 204 No Content

レコードの削除

これらの例は、レコードを削除するときの組織データ サービスと Web API の違いを示しています。

要求:

DELETE https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
Accept: application/json

応答:

HTTP/1.1 204 No Content

関連情報

Application Insights を使用して、2022 年 11 月に廃止される OrganizationData.svc エンドポイントの使用を識別する方法 (コミュニティ フォーラム)
ソリューション チェッカーを使用して、2022 年 11 月に廃止される OrganizationData.svc エンドポイントの使用を識別する方法 (コミュニティ フォーラム)
Microsoft Dataverse Web API の使用