ソリューションファイルを使用したカスタム API を作成する

[アーティクル]
07/14/2023

注意

これは、これらのトピックをすでに読んで、理解していることを前提とした高度なトピックです:

デザイナーまたはコードを使用してカスタム API を作成できますが、ソリューション内のファイルを操作してカスタム API を定義することもできます。ソリューション内でファイルを使うことは、アプリケーションライフサイクル管理 (ALM) の推奨されるベストプラクティスを適用するソリューション発行者に適したオプションです。

ソリューションファイルは、Microsoft Dataverse インスタンスからエクスポートされた圧縮 (zip) ファイルです。このファイルの内容を展開して、コンポーネントをソースリポジトリにチェックインできます。内容を編集して、再度圧縮できます。ソリューションに適用された変更は、ソリューションの一部になり、ソリューションのインポート時に作成されます。

注意

これらのプロセスは通常、このトピックの範囲外のツールとプロセスを使用して自動化されます。このトピックでは、ソリューションで展開されたファイルを手動で操作して、カスタム API を作成するという単純なシナリオに焦点を当て、ファイル内のデータを使用してカスタム API を作成する方法について説明します。詳細情報 : ソリューションファイルによるソース管理

手順 1: アンマネージドソリューションを作成する

ソリューションファイルを手動で作成しようとしないでください。 Power Apps のツールを使用して、ソリューションファイルを生成します。次の記事の手順を使用して、ソリューションを作成およびエクスポートします。ソリューションには、ソリューションコンポーネントを含める必要はありません。

ソリューションの作成

この例では、ソリューションは次のように簡単に定義されています:
ソリューションのエクスポート

この例では、アンマネージドソリューションをエクスポートしてください。管理ソリューションが既定です。

エクスポートしたファイルは、ダウンロードフォルダーにあります。この場合、ソリューションの名前とバージョンに応じた名前になります: CustomAPIExample_1_0_0_2.zip。

手順 2: ソリューションの内容を展開し、バージョンを更新する

ソリューションは、圧縮 (zip) ファイルです。

ファイルを右クリックして、コンテキストメニューから すべて展開... を選択します。

フォルダ内に次の 3 つのファイルが表示されます:
- [Content_Types].xml
- customizations.xml
- solution.xml

solution.xml ファイルを開いて、Version 要素を見つけます。

<ImportExportXml version="9.1.0.23474" SolutionPackageVersion="9.1" languagecode="1033" generatedBy="CrmLive" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SolutionManifest>
    <UniqueName>CustomAPIExample</UniqueName>
    <LocalizedNames>
      <LocalizedName description="Custom API Example" languagecode="1033" />
    </LocalizedNames>
    <Descriptions />
    <Version>1.0.0.1</Version>

値を 1 更新します。この例の場合、<Version>1.0.0.2</Version> です。
ファイルを保存します。

手順 3: カスタム API の定義を追加する

ソリューション内のすべてのカスタム API は、customapis という名前のフォルダー内にあります。そのフォルダー内で各カスタム API は、カスタム API の UniqueName プロパティに基づく名前が付いたフォルダーにあります。フォルダー内で、カスタム API を表すデータは、customapi.xml という名前の XML ファイル内にあります

展開したファイルのあるフォルダーに、customapis という名前の新しいフォルダーを作成します。
customapis フォルダーに、作成するカスタム API の UniqueName を使用してフォルダーを作成します。この例では、sample_CustomAPIExample を使用します。
作成した sample_CustomAPIExample フォルダーに、customapi.xml という名前のファイルを作成します。

customapi.xml を編集して、作成するカスタム API のプロパティを設定します。この例では、次の xml を使用します:

<customapi uniquename="sample_CustomAPIExample">
  <allowedcustomprocessingsteptype>0</allowedcustomprocessingsteptype>
  <bindingtype>0</bindingtype>
  <boundentitylogicalname />
  <description default="A simple example of a custom API">
    <label description="A simple example of a custom API" languagecode="1033" />
  </description>
  <displayname default="Custom API Example">
    <label description="Custom API Example" languagecode="1033" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <executeprivilegename />
  <isfunction>0</isfunction>
  <isprivate>0</isprivate>
  <name>sample_CustomAPIExample</name>
  <plugintypeid />
</customapi>

カスタム API テーブルの列を参照して、要素の値を設定します。

プラグインタイプとの関係を設定します (オプション)

このカスタム API に関連付けるプラグインの種類がすでにある場合は、<customapi> 要素内に次の要素を追加することで、この定義にプラグインの種類への参照を含めることができます:

<plugintypeid>
   <plugintypeexportkey>{Add the GUID value of the plug-in type export key}</plugintypeexportkey>
</plugintypeid>

<plugintypeid>
 <plugintypeid>{Add the GUID value of the plug-in type id}</plugintypeid>
</plugintypeid>

注意

どちらの値も機能しますが、plugintypeexportkey を使用することをお勧めします。

プラグインの種類名がわかっている次のような Web API クエリを使用して、PluginTypeExportKey と PluginTypeId を取得できます。

GET [Organization Uri]/api/data/v9.2/plugintypes?$select=name,plugintypeid,plugintypeexportkey&$filter=contains(name,'MyPlugin.TypeName')

手順 4: カスタム API の要求パラメーターを追加する

カスタム API の要求パラメーターの定義は、customapirequestparameters というフォルダーに含まれています。そのフォルダー内で各カスタム API の要求パラメーターは、カスタム API の要求パラメーターの UniqueName プロパティに基づく名前が付いたフォルダーにあります。

カスタム API に要求パラメーターがある場合は、前の手順で作成したカスタム API のフォルダー内に、customapirequestparameters という名前のフォルダーを作成します。
カスタム API 要求パラメーターごとに、カスタム API 要求パラメーターの UniqueName プロパティを使用して、新しいフォルダーを作成します。この例では、StringParameter を使用します。
フォルダ内に、customapirequestparameter.xml という名前の xml ファイルを追加します。
customapirequestparameter.xml ファイルを編集して、作成するカスタム API のプロパティを設定します。この例では、以下を使用します:

<customapirequestparameter uniquename="StringParameter">
  <description default="The StringParameter request parameter for custom API Example">
    <label description="The StringParameter request parameter for custom API Example" languagecode="1033" />
  </description>
  <displayname default="Custom API Example String Parameter">
    <label description="Custom API Example String Parameter" languagecode="1033" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <isoptional>0</isoptional>
  <logicalentityname />
  <name>sample_CustomAPIExample.StringParameter</name>
  <type>10</type>
</customapirequestparameter>

各要素の値を設定するには、CustomAPIRequestParameter テーブルの列の情報を参照してください。

手順 5: カスタム API の応答プロパティを追加する

カスタム API の応答プロパティの定義は、customapiresponseproperties というフォルダーに含まれています。そのフォルダー内で各カスタム API の応答プロパティは、カスタム API 応答プロパティの UniqueName プロパティに基づく名前が付いたフォルダーにあります。

カスタム API に応答プロパティがある場合は、手順 3: カスタム API の定義を追加するで作成したカスタム API のフォルダー内に、customapiresponseproperties という名前のフォルダーを作成します。
カスタム API の応答プロパティごとに、カスタム API 応答プロパティの UniqueName プロパティを使用して、新しいフォルダーを作成します。この例では、StringProperty を使用します。
フォルダ内に、customapiresponseproperty.xml という名前の xml ファイルを追加します。
customapiresponseproperty.xml ファイルを編集して、作成するカスタム API のプロパティを設定します。この例では、以下を使用します:

<customapiresponseproperty uniquename="StringProperty">
  <description default="The StringProperty response property for custom API Example">
    <label description="The StringProperty response property for custom API Example" languagecode="1033" />
  </description>
  <displayname default="Custom API Example String Property">
    <label description="Custom API Example String Property" languagecode="1033" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <logicalentityname />
  <name>sample_CustomAPIExample.StringProperty</name>
  <type>10</type>
</customapiresponseproperty>

各要素の値を設定するには、CustomAPIResponseProperty テーブルの列の情報を参照してください。

注意

要求パラメーターと応答プロパティのスキーマは非常に似ていますが、isoptional は応答プロパティには無効であり、ソリューションをインポートしようとするとエラーが発生することに注意してください。

手順 6: ファイルを圧縮して、新しいソリューションファイルを作成する

手順 2: ソリューションの内容を展開し、バージョンを更新するで元のソリューションファイルを展開したフォルダーに戻ります
展開したファイルと作成した customapis フォルダをすべて選択します。
選択したファイルを右クリックし、送信先 > 圧縮 (zip 形式のフォルダー) を選択します。
生成されたファイルの名前を任意の名前に変更できます。この例では、元のエクスポートしたソリューションファイルと一致するように名前を変更します: CustomAPIExample_1_0_0_2.zip。

手順 7: カスタム API の定義を使用してソリューションをインポートする

Power Apps に戻り、ソリューション を選択します。
インポート を選択し、指示に従って、前の手順で作成したソリューションファイルを選択します。

注意

このバージョンのソリューションパッケージは既にインストールされています という警告が表示された場合、手順 2: ソリューションの内容を展開し、バージョンを更新するで説明したように、solution.xml の Version 要素を更新しなかった可能性があります。
このソリューションパッケージには、既にインストールされているソリューションの更新が含まれています という警告が表示されます。 インポート を選んで続行します。
ソリューションのインポートが完了するまで数分待ちます。

注意

別のソリューションが同時にインストールされている場合、エラーが表示される可能性があります。詳細: ソリューションのインストールまたは削除が失敗しました。別のソリューションのインストールまたは削除が同時に行われていることが原因です

手順 8: カスタム API がソリューションに追加されたことを確認する

作成したソリューションを開き、カスタム API と関連する要求パラメーターおよび応答プロパティが含まれていることを確認します。

ソリューションコンポーネントが正常にインストールされたことを示す。

この時点で、カスタム API をテストするで説明されている手順を使用して API をテストできます

ソリューションのカスタム API を更新する

カスタム API を含むソリューションを出荷した後、アンマネージドソリューションのカスタム API に変更を加えることができます。新しいパラメータまたは応答プロパティを追加し、displayname および description などの更新をサポートする列に変更を加えることができます。

重要

保存後に変更できないプロパティを修正するソリューションでは、カスタム API に変更を導入することはできません。カスタム API の定義を含む新しいバージョンのソリューションをインストールするとき、カスタム API、カスタム API の要求パラメーター、およびカスタム API の応答プロパティを更新しようとします。ソリューションの更新は、他の方法でカスタム API を更新しようとするのと同じです。

カスタム API の作成後に変更できないソリューションファイルのプロパティは次のとおりです。

カスタム API プロパティ:
- allowedcustomprocessingsteptype
- bindingtype
- boundentitylogicalname
- isfunction
- uniquename
- workflowsdkstepenabled
カスタム API RequestParameter プロパティ:
- isoptional
- logicalentityname
- type
- uniquename
カスタム API 応答プロパティ:
- logicalentityname
- type
- uniquename

詳細: CustomAPI テーブル

ソリューションでローカライズされたラベルを提供する

ローカライズされたラベルの値で説明されているプロセスを使用する代わりに、カスタム API エンティティのソリューションファイルを編集している場合は、これらのファイルで直接翻訳を提供することができます。たとえば、カスタム API に日本語のローカライズされたラベルを提供する場合は、以下に示すように、description と displayname プロパティにラベルを提供できます:

<customapi uniquename="sample_CustomAPIExample">
  <allowedcustomprocessingsteptype>0</allowedcustomprocessingsteptype>
  <bindingtype>0</bindingtype>
  <description default="A simple example of a custom API">
    <label description="A simple example of a custom API" languagecode="1033" />
    <label description="カスタムAPIの簡単な例" languagecode="1041" />
  </description>
  <displayname default="Custom API Example">
    <label description="Custom API Example" languagecode="1033" />
    <label description="カスタムAPIの例" languagecode="1041" />
  </displayname>
  <iscustomizable>0</iscustomizable>
  <isfunction>0</isfunction>
  <name>sample_CustomAPIExample</name>
</customapi>

参照

カスタム API の作成と使用
 CustomAPI テーブル
 プラグイン登録ツールを使用してカスタム API を作成する
 Power Apps でカスタム API を作成する
 コードを使用したカスタム API を作成する
 独自のメッセージを作成する

注意

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

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

次の方法で共有

ソリューションファイルを使用したカスタム API を作成する

手順 1: アンマネージドソリューションを作成する

手順 2: ソリューションの内容を展開し、バージョンを更新する

手順 3: カスタム API の定義を追加する

プラグインタイプとの関係を設定します (オプション)

手順 4: カスタム API の要求パラメーターを追加する

手順 5: カスタム API の応答プロパティを追加する

手順 6: ファイルを圧縮して、新しいソリューションファイルを作成する

手順 7: カスタム API の定義を使用してソリューションをインポートする

手順 8: カスタム API がソリューションに追加されたことを確認する

ソリューションのカスタム API を更新する

ソリューションでローカライズされたラベルを提供する

参照

その他のリソース

次の方法で共有

ソリューション ファイルを使用したカスタム API を作成する

手順 1: アンマネージド ソリューションを作成する

手順 2: ソリューションの内容を展開し、バージョンを更新する

手順 3: カスタム API の定義を追加する

プラグイン タイプとの関係を設定します (オプション)

手順 4: カスタム API の要求パラメーターを追加する

手順 5: カスタム API の応答プロパティを追加する

手順 6: ファイルを圧縮して、新しいソリューション ファイルを作成する

手順 7: カスタム API の定義を使用してソリューションをインポートする

手順 8: カスタム API がソリューションに追加されたことを確認する

ソリューションのカスタム API を更新する

ソリューションでローカライズされたラベルを提供する

参照

その他のリソース

ソリューションファイルを使用したカスタム API を作成する

手順 1: アンマネージドソリューションを作成する

プラグインタイプとの関係を設定します (オプション)

手順 6: ファイルを圧縮して、新しいソリューションファイルを作成する