カスタム API の作成と使用

[アーティクル]
05/12/2022

Dataverse で独自の API を作成するカスタム API を使用します。 1 つ以上の操作をカスタム API に統合して、自分や他の開発者がコード内で、または Power Automate から呼び出せるようにすることができます。 Microsoft Dataverse コネクタにより、Power Automate のアクションを呼び出すことができます。

カスタム API をビジネスイベントとして使用して、Microsoft Dataverse コネクタの新しい種類のトリガーイベントを公開するなどの新しい統合機能を作成できるようにすることができます。詳細情報: Microsoft Dataverse ビジネスイベント

カスタム API は、カスタムプロセスアクションの代替手段です。カスタムプロセスアクションは、カスタムメッセージを含めるためのコード不要の方法を提供しますが、開発者にはいくつかの制限があります。カスタム API は、開発者がコードでその他のオプションを使用してロジックを定義するための機能を提供します。カスタムプロセスアクションとカスタム API の完全な比較については、カスタムプロセスアクションとカスタム API の比較を参照してください。

カスタム API の作成

カスタム API には、プラグインで実装されたロジックが含まれることがあります。 Microsoft Dataverse ビジネスイベントを使用して、プラグインなしでカスタム API を作成して、他のサブスクライバーが応答するイベントに関するデータを渡すことができます。

ただし、その他の場合は、カスタム API とプラグインと組み合わせて、Dataverse に委任して結果を計算して返す操作を定義します。

カスタム API の作成には、いくつかの方法があります。

メソッドリンク	ベネフィット
プラグイン登録ツール	プラグインの開発に使用されるツールと統合された使いやすい GUI ツール。
Power Apps	フォームを使用してデータを入力します。個別のツールをインストールする必要はありません。カスタム API の各部分に個別のレコードを作成する必要があります。
コードを使用	データモデルを理解した後、Postman を使用してカスタム API をすばやく作成することができます。または、独自のエクスペリエンスを構築して、カスタム API を作成することもできます。
ソリューションファイルを使用	アプリケーションライフサイクル管理 (ALM) ツールを使用すると、ソースコードリポジトリに含まれているソリューションで XML ファイルを使用してカスタム API 定義を作成または変更できます。カスタム API は、ソースコードから生成されたソリューションをインポートするときに作成されます。

注意

Custom API のデータはテーブルに格納されていますが、これらのテーブルに対するモデル駆動型アプリの作成はサポートしていません。

カスタム API を操作するために、コミュニティが作成およびサポートするツールがいくつかあります。

カスタム API のカスタマイズ

カスタム API および関連するリクエストパラメーターやレスポンスプロパティを作成する際には、これらの API 定義が既定でカスタマイズ可能であることを理解することが重要です。これにより、アンマネージドソリューションでこれらの項目を反復して変更することができます。

重要

ソリューションを出荷またはデプロイする際には、マネージドソリューションを使用し、これらのコンポーネントの Is Customizable マネージドプロパティを常に false に設定しておくことを推奨します。これにより、マネージドソリューションを使用するユーザーが、ソリューションのこれらのコンポーネントを変更または削除できないように設定できます。このような変更は、カスタム API の元の定義に向けて記述されたコードを壊す可能性があります。

Is Customizable を false に設定する

Power Apps のソリューションから Is Customizable 管理プロパティを設定することができます。

Is Customizable 管理プロパティを設定する

これは、カスタム API、要求パラメーター、応答プロパティごとに個別に設定する必要があります。

詳細情報管理プロパティ

追加要求パラメーターと応答プロパティを追加する

これらのコンポーネントの Is Customizable 管理プロパティを false に設定した場合でも、新しい要求パラメーターや応答プロパティをカスタム API に追加することができます。ただし、要求パラメーターの追加は必須ではありません。カスタム API でカスタム処理手順を許可することを選択した場合、元の定義に追加されたこれらの追加のパラメーターとプロパティは、カスタム API によって作成されたメッセージに登録された他のプラグインで使用できます。カスタム要求パラメーターはオプションのみであるため、カスタム API のメイン操作に提供するプラグインには無視され、カスタム要求パラメーターの使用やカスタム応答プロパティの設定について責任を負いません。

カスタム API テーブル/エンティティ

カスタム API を作成するときに使用するテーブルと列の値に関する情報については、CustomAPI テーブルを参照してください。

カスタム処理手順の種類を選択する

次の表に、使用する必要があるカスタム API の カスタム処理手順の種類 (AllowedCustomProcessingStepType) について説明します。

オプション	使用する場合
なし	このカスタム API に設定されたプラグインの種類が、この操作の実行時に発生する唯一のロジックになる場合。別の開発者が、追加のロジックのトリガー、この操作の動作の変更、または操作のキャンセルをする可能性のある追加手順を登録することを許可しません。カスタム API がカスタマイズできない機能を提供する場合に使用します。
非同期のみ	他の開発者がこの操作の発生時を検出できるようにしたいが、操作のキャンセルや操作の動作のカスタマイズをできないようにしたい場合。他の開発者は非同期手順を登録して、この操作が発生したことを検出し、完了後に応答することができます。これは、ビジネスイベントパターンを使用している場合に推奨されるオプションです。ビジネスイベントは Power Automate のトリガーを作成し、このイベントが発生したときに使用できます。詳細情報: Microsoft Dataverse ビジネスイベント
同期と非同期	他の開発者が操作の動作を変更できるようにし、ビジネスロジックで指示されている場合はそれをキャンセルできるようにする場合。操作が成功した場合、他の開発者もこれを検出し、非同期で実行するロジックを追加することができます。ほとんどの Dataverse メッセージは、このように拡張機能を有効にします。メッセージがカスタマイズ可能なビジネスプロセスを表す場合にこれを使用します。

バインディングの種類の選択

バインディングは、操作を特定のテーブルに関連付ける OData の概念です。次の表に、使用する必要があるカスタム API の バインディングの種類 (BindingType) について説明します。

オプション	使用する場合
Global	操作が特定のテーブルに適用されない場合。
Entity	操作が特定のテーブルの単一レコードをパラメーターとして受け入れる場合。
EntityCollection	操作が変更を適用するとき、または特定のテーブルのコレクションを返す場合。

Entity または EntityCollection を選択すると、Web API の使用時に関数またはアクションの完全修飾名を使用する必要があります。完全修飾名は、Microsoft.Dynamics.CRM.<UniqueName of the Custom API> です。

Entity を選択した場合、種類が EntityReference で Target という名前の要求パラメーターが自動的に作成されます。作成する必要はありません。この値は、このメッセージに登録されているすべてのプラグインに渡されます。

EntityCollection を選択した場合、エンティティコレクションを表すパラメーターまたは応答プロパティは含まれません。このバインドを設定すると、Web API の使用時にエンティティセットに追加された操作が呼び出されるという要件が追加されます。

注意

これらのバインドの種類は、カスタム API を作成するときに使用できますが、エンティティまたはエンティティコレクションにバインドする必要はありません。すべてのカスタム API を Global として作成し、バインドされた関数またはアクションと同じ機能を実現するために必要な要求パラメーターまたは応答プロパティを追加します。

詳細情報:

関数を作成する場合

カスタム API の Is Function プロパティは、カスタム API が関数または アクション になるかどうかを制御します。 OData では、関数は変更を加えずにデータを返す HTTP GET 要求を使用して呼び出される操作です。 GET 要求を使用し、関数を呼び出すときにすべてのパラメーターが URL のパラメーターとして渡されます。

ブラウザーのみを使用してより簡単に GET 要求をテストできますが、送信できる URL の長さには制限があり、通常は約 2000 文字です。カスタム API には多くの複雑な要求パラメーターがあり、URL の長さが長くなりすぎる可能性がある場合は、POST 要求を使用する本文内のすべてのパラメーターデータを渡す、同じ操作を実行するアクションを作成することができます。

注意

関数はデータを返します。カスタム API を有効にするには、少なくとも 1 つの応答プロパティを含める必要があります。
- 応答プロパティを含まない関数は、Web API $metadata サービスドキュメント内に表示されません。
- 無効な関数を使用しようとすると、このような 404 Not found エラーが発生します。
  {"error":{"code":"0x8006088a","message":"Resource not found for the segment 'your_function_name'."}}
ワークフローで有効 オプションが選択されている場合、関数は許可されません。ワークフローでカスタム API を使用するを参照してください
現在、Microsoft Dataverse コネクタはアクションの実行のみを有効にします。 Power Automate を使用して操作を実行する必要がある場合、カスタム API をアクションとして作成する必要があります。

詳細情報: Web API 関数を使用

カスタム API を非公開にする場合

既定では、作成するカスタム API は、他の開発者が検出して使用できるようになります。カスタム API の公開元として、作成するパブリック API を維持する義務があります。 API を削除したり、他の消費者に破損をもたらすような変更を適用したりしないでください。

他の開発者がカスタム API を使用するのをサポートしない場合、カスタム API を含む管理ソリューションを送付する前に、カスタム API の Is Private (IsPrivate) プロパティを true に設定する必要があります。

Is Private プロパティは、カスタム API が $metadata サービスドキュメント内に表示されないようにブロックし、Dataverse コード生成ツールがカスタム API のメッセージを使用するためのクラスを作成するのを防止します。

これは、他の開発者がそのメッセージを知っていて、使用するための要求を作成できる場合、使用することができないという意味ではありません。 Is Private プロパティの設定は、他の開発者によるメッセージの使用をサポートしていないことを示す方法です。

カスタム API を削除したり、破壊的変更を加えたりする必要がないことが確実になるまで、カスタム API を非公開にしておくことができます。

開発環境において Is Private 設定を false にしておき、$metadata サービスドキュメントの出力を確認したり、独自に使用するクラスを生成したりすることができます。ただし、カスタム API を管理ソリューションで送付する前に、Is Private を true に設定する必要があります。

詳細情報:

特権でカスタム API を保護する

カスタム API の Execute Privilege Name (ExecutePrivilegeName) プロパティを要求する特権の名前に設定します。現在、Microsoft 以外の開発者が新しい権限を作成する方法はサポートされていませんが、既存の権限を使用できます。詳細: Q: カスタム API に新しい権限を作成できますか?

プラグインを使用して、カスタム API にロジックを含める

カスタム API の プラグインの種類 (PluginTypeId) を設定しないでメイン操作を指定する場合でも、カスタム API を呼び出すことができます。

カスタム API をビジネスイベントとして使用しているため、プラグインにロジックを含めないことを選択できます。詳細情報: Microsoft Dataverse ビジネスイベント。

これをテスト手順として実行することもできますが、出力パラメーター値を設定するコードがないため、出力パラメーター値は種類の既定値を返します。

ワークフローでカスタム API を使用する

カスタム API をワークフローアクションとして呼び出すことを有効にする必要がある場合、カスタム API の ワークフローで有効 (WorkflowSdkStepEnabled) を true に設定します。ただし、これを選択すると、ワークフローデザイナーでカスタム API を呼び出すことができるように、次の制限が課せられます。

カスタム API を関数にすることはできず、関数である は false でなければなりません。
カスタム API は、ワークフローがサポートするリクエストパラメータまたはレスポンスプロパティタイプのみを持つことができます。
- Boolean
- 日時
- Decimal
- EntityReference
  - EntityReference は、カスタム API がエンティティにバインドされている場合にのみ使用できます。
- Float
- Integer
- Money
- Picklist
- String
- GUID
次の要求パラメーターまたは応答プロパティの種類は使用できません。
- Entity
- EntityCollection
- StringArray

カスタム API の呼び出し

カスタム API は、他の操作と同じように Web API または組織サービス SDK を介して呼び出すことができる新しいメッセージを作成します。

Web API からのカスタム API の呼び出し

テスト中に、PostMan を使用して API を呼び出すことができます。 Postman 環境を設定するに記載の手順を使用して PostMan 環境を設定し、必要なアクセストークンを生成します。次に、API がアクションである場合は、Web API のアクションを使用するで説明されている手順を適用します。関数の場合は、Web API 関数を使用するの手順を使用します。

次の例を参照してください。

バインドされていないアクション

このアクションの名前は、myapi_CustomUnboundAPI です。 InputParameter という名前の単一文字列要求パラメーターがあります。

POST [Organization URI]/api/data/v9.1/myapi_CustomUnboundAPI
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

{
  "InputParameter": "Value"
}

バインド済みアクション

myapi_CustomBoundAPI という名前のアクションは、アカウントテーブルにバインドされています。

GET [Organization URI]/api/v9.1/accounts(ed5d4e42-850c-45b7-8b38-2677545107cc)/Microsoft.Dynamics.CRM.myapi_CustomBoundAPI()
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

バインド済み関数

myapi_CustomEntityCollectionBoundAPI という名前の関数は、アカウントテーブルコレクションにバインドされています。

GET [Organization URI]/api/v9.1/accounts/Microsoft.Dynamics.CRM.myapi_CustomEntityCollectionBoundAPI()
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

詳細情報:

組織サービスからのカスタム API の呼び出し

早期バインド済みまたは遅延バインド済みのコードのいずれかを使用して、カスタム API を呼び出すことができます。 CrmSvcUtil ツールを使用して、カスタム API の要求パラメーターと応答プロパティを公開するためのヘルパー要求クラスと応答クラスを生成します。

遅延バインディングコードや、非公開に設定したカスタム API の場合は、カスタム API の固有名で OrganizationRequest を作成し、要求プロパティの固有名と一致する名前のパラメーターを追加します。

エンティティバインド済みのカスタム API には、API 上で呼び出すレコードの EntityReference を設定する必要がある、Target という名前の暗黙的なリクエストプロパティがあります。

返された応答のパラメーターから応答プロパティにアクセスできます。

この例では myapi_EscalateCase という名前のカスタム API が、Priority という名前の他のオプションセット値要求パラメーターと共に、Target パラメーターとしてレコードを受け入れるようにインシデントテーブルにバインドされます。 AssignedTo という名前の EntityReference 応答プロパティがあります。

var req = new OrganizationRequest("myapi_EscalateCase")
{
  ["Target"] = new EntityReference("incident", guid),
  ["Priority"] = new OptionSetValue(1)
};

var resp = svc.Execute(req);

var newOwner = (EntityReference) resp["AssignedTo"];

詳細情報: 組織サービスでメッセージを利用する。

カスタム API で使用するプラグインを記述する

カスタム API のメイン操作を実装するプラグインを記述することは、プラグイン登録ツールを使用して特定のステップを設定しないことを除けば、他の種類のプラグインを記述することと変わりません。

次の情報を知っておく必要があります:

メッセージの名前
要求パラメーターと応答プロパティの名前と種類。

要求パラメータの値は、InputParameters に含まれます。

OutputParameters の応答パラメーターで使用する値を設定する必要があります。

以下は、StringParameter の文字を逆にして結果を StringProperty として返す簡単なプラグインです。

using System;
using System.Linq;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

namespace CustomAPIExamples
{
    public class Sample_CustomAPIExample : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            // Obtain the execution context from the service provider.  
            IPluginExecutionContext context = (IPluginExecutionContext)
                serviceProvider.GetService(typeof(IPluginExecutionContext));

            if (context.MessageName.Equals("sample_CustomAPIExample") && context.Stage.Equals(30)) {

                try
                {
                    string input = (string)context.InputParameters["StringParameter"];
                    
                    if (!string.IsNullOrEmpty(input)) {
                        //Simply reversing the characters of the string
                        context.OutputParameters["StringProperty"] = new string(input.Reverse().ToArray());
                    }
                }
                catch (Exception ex)
                {
                    tracingService.Trace("Sample_CustomAPIExample: {0}", ex.ToString());
                    throw new InvalidPluginExecutionException("An error occurred in Sample_CustomAPIExample.", ex);
                }
            }
            else
            {
                tracingService.Trace("Sample_CustomAPIExample plug-in is not associated with the expected message or is not registered for the main operation.");
            }
        }
    }
}

プラグインの作成の詳細については、チュートリアル : プラグインを作成して登録するを参照してください。アセンブリの登録は必要ですが、手順の登録は必要ありません。詳細情報: プラグインを使用して、カスタム API にロジックを含めるを参照してください

サンプル: IsSystemAdmin カスタム API の例を参照してください

アセンブリの登録後は、必ずアセンブリと任意のタイプをソリューションに追加してください。

ローカライズされたラベルの値

カスタム API には、ローカライズ可能なラベルがいくつかあります。ラベルの値をローカライズするには、次で説明している手順に従う必要があります : モデル駆動型アプリに向けたローカライズされたテキストを翻訳するとラベルや表示文字列の翻訳。

このプロセスには、基本言語の値を含むファイルをエクスポートし、有効になっている各追加言語に列を含めます。その後、Excel で値を編集できます。翻訳をインポートするプロセスを完了すると、ラベルがソリューションに含まれます。

次の例は、Excel ワークシートを編集して、英語の値に日本語翻訳を追加する方法を示しています。

ラベルがどのようにローカライズされているかを示します。

ヒント

ソリューションファイルを編集して、カスタム API を作成する場合は、ローカライズされたラベルを直接提供できます。詳細: ソリューションでローカライズされたラベルを提供する

ローカライズされた値の設定

上記の手動プロセスを使用するのではなく、コードでローカライズされたラベルを設定したい場合は、WebAPIのいずれかを使用した SetLocLabels メッセージSetLocLabels アクションまたは組織サービス SetLocLabelsRequest を使用できます。

次の例は、WebAPI を使用して、カスタム API の displayname プロパティのローカライズされたラベルを設定する方法を示しています。

要求

POST [Organization URI]/api/data/v9.1/SetLocLabels HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json

{
    "EntityMoniker": {
        "@odata.type": "Microsoft.Dynamics.CRM.customapi",
        "customapiid": "86bcd12e-2f30-eb11-a813-000d3a122b89"
    },
    "AttributeName": "displayname",
    "Labels": [
        {
            "Label": "例え",
            "LanguageCode": 1041
        },
        {
            "Label": "Beispiel",
            "LanguageCode": 1031
        },
        {
            "Label": "ejemplo",
            "LanguageCode": 1034
        }
    ]
}

回答

HTTP/1.1 204 No Content

ローカライズされた値の取得

ローカライズされたラベルを取得するには、Web API の RetrieveLocLabels 関数または組織サービスの RetrieveLocLabelsRequest のいずれかを使用して、RetrieveLocLabels メッセージを使用します。

次の例は、RetrieveLocLabels 関数を使用して、カスタム API の displayname プロパティのラベルを 88602189-183d-4584-ba4b-8b60f0f5b89f の customapiid で取得する方法を示しています

要求

GET [Organization URI]/api/data/v9.1/RetrieveLocLabels(EntityMoniker=@p1,AttributeName=@p2,IncludeUnpublished=@p3)?
@p1={'@odata.id':'customapis(88602189-183d-4584-ba4b-8b60f0f5b89f)'}&
@p2='displayname'&
@p3=false HTTP/1.1

回答

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveLocLabelsResponse",
    "Label": {
        "LocalizedLabels": [
            {
                "Label": "Custom API Example",
                "LanguageCode": 1033,
                "IsManaged": null,
                "MetadataId": null,
                "HasChanged": null
            },
            {
                "Label": "カスタムAPIの例",
                "LanguageCode": 1041,
                "IsManaged": null,
                "MetadataId": null,
                "HasChanged": null
            }
        ],
        "UserLocalizedLabel": {
            "Label": "Custom API Example",
            "LanguageCode": 1033,
            "IsManaged": null,
            "MetadataId": null,
            "HasChanged": null
        }
    }
}

よく寄せられる質問 (FAQ)

以下のような質問があります:

Q: カスタム API に新しい権限を作成できますか?

A: カスタム API には実行する権限名 (ExecutePrivilegeName) プロパティがありますが、現在、この API 専用の新しい権限を作成する方法はサポートされていません。これは、今後のリリースで予定されています。それまでの間、2 つのオプションがあります:

既存の Privilege.Name 値を使用できます。
カスタムエンティティを作成し、そのエンティティ用に作成された権限の 1 つを使用できます。たとえば、new_myaction という名前のエンティティを作成すると、CRUD 操作の権限が生成されます。たとえば、prvCreatenew_myaction。カスタム API を含むソリューションと共に、このカスタムエンティティを含める必要があります。

Q: カスタム API レコードをアクティブ化または非アクティブ化できますか?

A: できません。これらのレコードには、ほとんどの Microsoft Dataverse テーブルに見られる共通の状態と ステータス の列があります。これらの列の値を設定しても、カスタム API の可用性、リクエストパラメーター、レスポンスプロパティには影響しません。

Q: 非公開メッセージが Web API $Metadata Service ドキュメントに含まれていない場合、どうすれば使用できますか?

A: 非公開メッセージは、Web API CSDL $Metadata ドキュメントで通知されているかどうかに関係なく機能します。ソリューションを開発している間、IsPrivate 値を false に設定したままにしておくことができます。この方法により、$metadata の一覧を参照し、このデータに依存するコード生成ツールを使用できます。ただし、他のユーザーが使用できるようにソリューションを送る前に、CustomAPI.IsPrivate の値を true に設定する必要があります。後で、メッセージを使用する他のアプリケーションをサポートする場合、CustomAPI.IsPrivate の値を false に変更できます。

詳細情報:

カスタム API を非公開にする場合
プライベートメッセージ
プライベートメッセージはプラグインでは使用できません

カスタム API に関する既知の問題

カスタム API が一般的に利用できるようになっていますが、まだ関連する機能で変更が予定されています。

デバッグにプロファイラーを使用できません

プラグイン登録ツールとプラグインプロファイラーソリューションを使用してデバッグするには、特定のプラグインステップを選択できる必要があります。プラグイン用のメインステージの実装は、現在プラグイン登録ツールでは利用できません。

回避策 : カスタム API 用に作成したメッセージの PostOperation ステージにプラグインタイプを登録します。

プライベートメッセージはプラグインでは使用できません

カスタム API をプライベートとして定義した場合、そのメッセージをプラグインで使用することはできません。詳細丈夫: 非公開メッセージ

次のステップ

プラグイン登録ツールを使用してカスタム API を作成する

参照

カスタム API の作成と使用
 コードを使用したカスタム API の作成
 ソリューションファイルを使用したカスタム API の作成
 独自のメッセージを作成する
 カスタム API テーブル

注意

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

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

カスタム API の作成と使用

カスタム API の作成

カスタム API のカスタマイズ

Is Customizable を false に設定する

追加要求パラメーターと応答プロパティを追加する

カスタム API テーブル/エンティティ

カスタム処理手順の種類を選択する

バインディングの種類の選択

関数を作成する場合

カスタム API を非公開にする場合

特権でカスタム API を保護する

プラグインを使用して、カスタム API にロジックを含める

ワークフローでカスタム API を使用する

カスタム API の呼び出し

Web API からのカスタム API の呼び出し

バインドされていないアクション

バインド済みアクション

バインド済み関数

組織サービスからのカスタム API の呼び出し

カスタム API で使用するプラグインを記述する

ローカライズされたラベルの値

ローカライズされた値の設定

ローカライズされた値の取得

よく寄せられる質問 (FAQ)

Q: カスタム API に新しい権限を作成できますか?

Q: カスタム API レコードをアクティブ化または非アクティブ化できますか?

Q: 非公開メッセージが Web API $Metadata Service ドキュメントに含まれていない場合、どうすれば使用できますか?

カスタム API に関する既知の問題

デバッグにプロファイラーを使用できません

プライベート メッセージはプラグインでは使用できません

次のステップ

参照

フィードバック

プライベートメッセージはプラグインでは使用できません