カスタム API の作成と使用

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 や Insomnia などの API クライアントを使用して、カスタム API をすばやく作成することができます。または、独自のエクスペリエンスを構築して、カスタム API を作成することもできます。
ソリューションファイルを使用	アプリケーションライフサイクル管理 (ALM) ツールを使用すると、ソースコードリポジトリに含まれているソリューションで XML ファイルを使用してカスタム API 定義を作成または変更できます。カスタム API は、ソースコードから生成されたソリューションをインポートするときに作成されます。

注意

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

これらのツールは、カスタム API を操作するためにコミュニティによって作成およびサポートされています。

Microsoft では、コミュニティで作成されたツールはサポートされていません。コミュニティツールに関する質問や問題は、ツールの公開元にお問い合わせください。

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

カスタム API と関連する要求パラメーターと応答プロパティを作成するときは、これらの API 定義が既定でカスタマイズ可能であることを理解してください。カスタマイズ可能な場合は、アンマネージドソリューションでこれらの項目を反復処理して変更できます。

重要

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

Is Customizable を false に設定する

Power Apps でソリューションから [カスタマイズ可能] 管理プロパティを設定します。

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

このプロパティは、カスタム API、要求パラメーター、応答プロパティごとに個別に設定します。

管理プロパティの詳細を確認します。

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

[カスタマイズ可能な管理プロパティ] をfalseに設定した場合でも、新しい要求パラメーターと応答プロパティをカスタム API に追加できます。ただし、これらの要求パラメーターを追加するユーザーは、それらを必須にすることはできません。カスタム API でカスタム処理ステップを許可することを選択した場合、カスタム API で作成されたメッセージに対して登録された他のプラグインは、それらを使用することができます。カスタム要求パラメーターは省略可能なだけであるため、カスタム API のメイン操作用に指定したプラグインはそれらを無視でき、カスタム要求パラメーターを使用したり、指定したカスタム API に追加されたカスタム応答プロパティを設定したりする責任はありません。

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

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

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

次の表では、使用するカスタム API カスタム処理ステップの種類 (AllowedCustomProcessingStepType) について説明します。

回答内容	使用する場合
なし	CustomAPI.PluginTypeId を使用してこのカスタム 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> です。

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

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

注意

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

詳細情報:

関数を作成する場合

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

ブラウザーのみを使用して GET 要求をより簡単にテストできますが、送信できる URL の長さに 32 KB (32,768 文字) の制限があります。カスタム 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 Connector ではアクションの実行のみが有効です。 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 を非公開にしておくことができます。

開発環境で [プライベート] を 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 をワークフローアクションとして呼び出すことを有効にする必要がある場合、カスタム API のワークフローで有効 (WorkflowSdkStepEnabled) を true に設定します。ただし、このオプションでは、ワークフローデザイナーでカスタム API を呼び出すことができるように、次の制限が追加されます。

カスタム API を関数にすることはできません。 関数である は false である必要があります。
カスタム API は、ワークフローがサポートするリクエストパラメータまたはレスポンスプロパティタイプのみを持つことができます。
- ブール値
- 日時
- Decimal
- EntityReference
  - EntityReference は、カスタム API がエンティティにバインドされている場合にのみ使用できます。
- 浮動
- 整数
- お金
- Picklist
- 文字列
- GUID
次の要求パラメーターまたは応答プロパティの種類は使用できません。
- エンティティ
- EntityCollection
- StringArray

カスタム API の呼び出し

カスタム API は、他の操作と同様に、ユーザーが Web API または Dataverse SDK for .NET を介して呼び出すことができる新しいメッセージを作成します。

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

テスト中は、Postman や不眠症などの API クライアントを使用して API を呼び出すことができます。必要なアクセストークンを生成する不眠症環境を設定するには、「 Dataverse Web API で不眠症を使用する」を参照してください。 API がアクションの場合は、「 Web API アクションを使用する」の手順に従います。 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

詳細情報:

SDK for .NET からカスタム API を呼び出す

カスタム API を呼び出すには、早期バインドまたは遅延バインドのコードを使用します。 pac modelbuilder ビルドツールを使用して、カスタム API の要求パラメーターと応答プロパティを公開するヘルパー要求クラスと応答クラスを生成します。 .NET 用 SDK のアーリーバウンドクラスの生成については、こちらをご覧ください。

遅延バインディングコードの場合、またはプライベートとしてマークするカスタム API の場合は、カスタム API の一意の名前を持つ OrganizationRequest を作成します。要求プロパティの一意の名前と一致する名前を持つパラメーターを追加します。

エンティティバインドカスタム API には、 Targetという名前の暗黙的な要求プロパティがあります。このプロパティを、API を呼び出すレコードの EntityReference に設定します。

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

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

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"];

メッセージを .NET 用 SDK と共に使用する方法を参照してください。

カスタム API をバックグラウンド操作として呼び出す

バックグラウンド操作を使用して実行するロジックは、カスタム API として定義する必要があります。バックグラウンド操作を使用する方法 (プレビュー)

カスタム API 用のプラグインを作成する

カスタム API のメイン操作を実装するためのプラグインの記述は、他のプラグインの記述と同じではありません。ただし、プラグイン登録ツールを使用して特定の手順を設定しないでください。また、プラグインに渡す構成データを指定することはできません。

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

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

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

OutputParameters の Response プロパティの値を設定します。

以下のコードは、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 を作成する場合は、ローカライズされたラベルを直接指定できます。ソリューションでローカライズされたラベルを提供する方法について説明します

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

前述の手動プロセスを使用するのではなく、コードでローカライズされたラベルを設定する場合は、Web API SetLocLabelsまたは SDK for .NET を使用して、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または SDK for .NET RetrieveLocLabelsRequest クラスを使用して、メッセージを使用します。

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

要求:

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 には Execute Privilege Name (ExecutePrivilegeName) プロパティがありますが、現在、この API に対して新しい特権を作成する方法はサポートされていません。この機能は、将来のリリースで計画されています。それまでは、次のいずれかのオプションを使用します。

既存の Privilege.Name 値を使用します。
カスタムエンティティを作成し、そのエンティティに対して作成された特権のいずれかを使用します。たとえば、new_myaction という名前のエンティティを作成すると、CRUD 操作の権限が生成されます。例: prvCreatenew_myaction。このカスタムエンティティを、カスタム API を含むソリューションに含めます。

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

A: できません。これらのレコードには、ほとんどの Microsoft Dataverse テーブルで共通の Status 列と Status Reason 列がありますが、これらの列の値を設定しても、カスタム 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 に関連付けるのではなく、プラグイン登録ツール (PRT) を使用して、 PostOperation ステージにプラグインを登録します。この方法を使用すると、通常と同様に、 PostOperation プラグインの手順で構成データを指定できます。

この回避策を使用するには、カスタム API を作成するときに Sync と Asyncのカスタム処理ステップの種類を有効にするようにカスタム API を構成する必要があります。この設定は、作成後に変更することはできません。

次のステップ

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

参照

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

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-01-10

次の方法で共有

カスタム API の作成と使用