CDSWebApiService クラス ライブラリ (C#)

注意

エンティティとテーブルの違いがわかりませんか？ Microsoft Dataverse で「開発者: 用語を理解する」を参照してください。

Microsoft Dataverse のWeb API で JSON オブジェクトと一般的な HTTP メッセージング操作を使用する .NET Framework サンプル クラス ライブラリです。 これらのクラスメソッドを使用すると、アプリケーション コードの複雑さが軽減され、パフォーマンスのベスト プラクティスが実装され、エラー処理が改善されます。

このクラス ライブラリでは、以下の方法を実演します :

• 一般的な操作を HTTP メソッドで折り返して、コードを「乾燥」させます。
• スレッドセーフな方法で HttpClient を管理します。
• クライアント アプリケーションで表示される、サービス保護の制限 API 429 要求が多すぎます エラーを管理します。
  • 詳しくは：サービス保護APIの制限を参照してください。

注意

このサンプル クラス ライブラリは、他のサンプルによって使用されるヘルパーです。 あらゆる種類のプロジェクトで再利用可能なコンポーネントとなることを意図したものではありません。

CDSWebApiService クラスライブラリのソース コードと Visual Studio ソリューションは PowerApps - サンプル/cds/webapi/C#/CDSWebApiService にあります。

例

この例では、CDSWebAPIService インスタンスをインスタンス化し、連絡先行を作成する方法を紹介しています。

この例では、次に示すように、接続文字列が App.config ファイルに設定されていることを想定しています。

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <startup>
    <supportedRuntime version="v4.0"
                      sku=".NETFramework,Version=v4.7.2" />
  </startup>
  <connectionStrings>
    <add name="Connect"
         connectionString="Url=https://yourorg.api.crm.dynamics.com;
         Authority=null;
         ClientId=51f81489-12ee-4a9e-aaae-a2591f45987d;
         RedirectUrl=app://58145B91-0C36-4500-8554-080854F2AC97;
         UserPrincipalName=you@yourorg.onmicrosoft.com;
         Password=y0urp455w0rd;
         CallerObjectId=null;
         Version=9.1;
         MaxRetries=3;
         TimeoutInSeconds=180;
         "/>
  </connectionStrings>
</configuration>

コードは、接続文字列にアクセスして、CDSWebApiService をインスタンス化します。

//Get configuration data from App.config connectionStrings
static readonly string connectionString = ConfigurationManager.ConnectionStrings["Connect"].ConnectionString;
static readonly ServiceConfig config = new ServiceConfig(connectionString);

    using (CDSWebApiService svc = new CDSWebApiService(config))
    {
        //Create a contact
        var contact1 = new JObject
            {
                { "firstname", "Rafel" },
                { "lastname", "Shillo" }
            };
        Uri contact1Uri = svc.PostCreate("contacts", contact1);
    }

プロパティ​​

このクラスは、BaseAddress プロパティのみを公開します。 これは、HttpClient が使用する構成済みの BaseAddress です。 ほとんどの場合、相対 URI が想定されるため、必要なときに完全な URI を作成すると便利です。

メソッド

このクラスには、次のパブリック メソッドが用意されています。

PostCreate

テーブル行 (エンティティ レコード) を同期的に作成し、URI を返します。

パラメーター

名称	タイプ	内容
entitySetName	String	作成するエンティティの種類についてのエンティティ セット名。
本文	JObject	エンティティが作成するデータの内容

戻り値

作成されたテーブル行 (エンティティレコード) の Uri

備考

エンティティの作成は一般的な操作であり、URI はOData-EntityId ヘッダーで返されるため、このメソッドが提供されます。 この特殊なメソッドを使用すると、JObject のみを返す Post メソッドのみを使用する場合よりコードを少なくできます。

詳細については、 Web API を使用してテーブル行を作成するを参照してください。

PostCreateAsync

PostCreate の非同期バージョン。

事後

POST 要求を同期的に送信し、応答を JObject として返します。

パラメーター

件名	種類​​	内容
path	String	要求を送信するための相対パス。 多くの場合、アクションの名前またはエンティティ セット名。
本文	JObject	POST へのペイロード
ヘッダー	Dictionary<string, List<string>>	(オプション) 特別な動作を適用するために必要なヘッダー

戻り値

応答を含む JObject。

備考

このメソッドは、POST HTTP メソッドを使用するすべての操作に使用できますが、応答コンテンツのみが含まれます。 PostCreate を使用してテーブル行 (エンティティ レコード) を作成し、作成した行の URI のみを返します。

詳細:

• 返されるデータで作成する
• Web API アクションの使用

PostAsync

Post の非同期バージョン。

修正プログラム

PATCH 要求を同期的に送信します。

パラメーター

件名	種類​​	内容
URI	Uri	要求を送信するための相対パス。 多くの場合、特定のテーブル行 (エンティティ レコード) の URI です
body	JObject	送信するペイロード
headers	Dictionary<string, List<string>>	(オプション) 特別な動作を適用するために必要なヘッダー

備考

パッチは、テーブルの行を更新またはアップサートする目的で頻繁に使用されます。

詳細:

• 基本的な更新
• テーブルの Upsert

PatchAsync

Patch の非同期バージョン。

取得

GET 要求を同期的に送信し、データを返す

パラメーター

件名	種類​​	内容
path	String	返すリソースへの相対パス
ヘッダー	Dictionary<string, List<string>>	(オプション) 特別な動作を適用するために必要なヘッダー

戻り値

要求されたデータを表す JToken。

備考

詳細:

• Web API を使用したクエリ データ
• Web API を使用してテーブルの行を取得する
• Web API 関数の使用

GetAsync

Get の非同期バージョン。

削除​​

DELETE 要求を同期的に送信します。

パラメーター

件名	種類​​	内容
URI	Uri	削除するリソースの相対パス
ヘッダー	Dictionary<string, List<string>>	(オプション) 特別な動作を適用するために必要なヘッダー

備考

詳細:

• 基本的な削除
• テーブルへの参照の削除
• 単一のプロパティ値の削除

DeleteAsync

削除 の非同期バージョン。

プット

PUT 要求を同期的に送信します。

パラメーター

件名	種類​​	内容
URI	Uri	更新するリソースへの相対パス。
property	String	更新する列の名前です
価値	String	設定する値

備考

Put は、特定のテーブル列を更新する目的で使用します。

注意: Http PUT メソッドは、テーブルまたは列の定義 (メタデータ) を更新する際にも使用されます。 このメソッドはその目的には使用できません。 ビジネス データ専用です。

詳細:

• 単一のプロパティ値の更新
• 単一値ナビゲーション プロパティでの参照の変更

PutAsync

Put の非同期バージョン。

プライベート SendAsync メソッド

上記のすべてのメソッドは、プライベートな SendAsync メソッドを介して要求をルーティングします。 ここで、低レベルの共通ロジックが発生します。

このメソッドには、サービス保護 API 429 エラーを管理し、サービスで構成可能な回数だけそれらを再試行するロジックが含まれています。

これを行うには、実際の要求ではなく要求のコピーを送信します。これは、要求が破棄され、エラーが返された場合は再度送信できないためです。

Extensions.cs ファイルで定義されたカスタム HttpRequestMessage Clone メソッドがあるため、要求のコピーを使用できます。

OAuthMessageHandler

内部 HttpClient が CDSWebApiService コンストラクターで初期化されると、このクラスのインスタンスが HttpMessageHandler として設定されます。 このクラスは ADAL ライブラリと連携して、要求が送信されるたびに accessToken が更新されるようにします。 accessToken の期限が切れると、ADAL ライブラリ メソッドが自動的に更新します。

詳細: DelegatingHandler を示す例

ServiceConfig

CDSWebApiService クラスは、ServiceConfig クラスを介して接続文字列で初期化する必要があります。

ServiceConfig コンストラクターは、通常は App.config 構成からの接続文字列を受け入れ、そこで定義されたデータは、CDSWebApiService コンストラクターが必要とする ServiceConfig インスタンスに解析されます。

プロパティ​​

ServiceConfig クラスのプロパティは次のとおりです。

件名	種類​​	内容
オーソリティ	String	許可されているユーザーに使用するオーソリティ。 既定: 「https://login.microsoftonline.com/common」
CallerObjectId	Guid	ユーザーが他のユーザーを偽装するための Azure AD ObjectId。
クライアント ID	String	Azure AD に登録されているアプリケーションの ID
MaxRetries	Byte	サービス保護の制限によってブロックされた要求を再試行する最大試行回数。 既定値は 3 です。
パスワード	SecureString	ユーザー プリンシパルのパスワード
RedirectUrl	String	Azure AD に登録されているアプリケーションのリダイレクト URL
TimeoutInSeconds	ushort	要求がキャンセルされる前に要求の完了を試みる時間。 既定値: 120 (2 分)
URL	String	Dataverse 環境の URL : 「https://yourorg.api.crm.dynamics.com」
UserPrincipalName	String	ユーザーのユーザー プリンシパル名。 すなわち、you@yourorg.onmicrosoft.com
バージョン	String	使用する Web API のバージョン。 既定: 「9.1」

接続文字列の例

CDSWebApiService を使用する各サンプルには、共通の App.config への参照と、「Connect」という名前の接続文字列値を読み取るコードが含まれています。 次に、その App.config の例を示します。

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <startup>
    <supportedRuntime version="v4.0"
                      sku=".NETFramework,Version=v4.7.2" />
  </startup>
  <connectionStrings>
    <add name="Connect"
         connectionString="Url=https://yourorg.api.crm.dynamics.com;
         Authority=null;
         ClientId=51f81489-12ee-4a9e-aaae-a2591f45987d;
         RedirectUrl=app://58145B91-0C36-4500-8554-080854F2AC97;
         UserPrincipalName=you@yourorg.onmicrosoft.com;
         Password=y0urp455w0rd;
         CallerObjectId=null;
         Version=9.1;
         MaxRetries=3;
         TimeoutInSeconds=180;
         "/>
  </connectionStrings>
</configuration>

ClientId と RedirectUrl の値は、サンプル アプリケーション用です。 これらを使用してサンプルを実行できますが、独自のアプリケーションを登録し、これらのプロパティに対応する値を入力する必要があります。

詳細: チュートリアル: Azure Active Directory でアプリを登録する

ServiceException

このクラスは単に Exception を拡張し、エラー応答から追加のプロパティを提供します。

プロパティ​​

件名	種類​​	内容
メッセージ	String	プラットフォームから返されたメッセージ
エラー コード	Int32	プラットフォームから返されたエラー コード
StatusCode	Int32	HttpResponseMessage.StatusCode
ReasonPhrase	String	HttpResponseMessage.ReasonPhrase

このクラスを使用したサンプル

このクラスを使用している C# のサンプルは以下の通りです :

• 基本操作のサンプル (C#)
• 並列操作のサンプル (C#)
• 非同期並列演算のサンプル (C#)
• 条件付き演算サンプル (C#)
• クエリ データのサンプル (C#)

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。