使用解决方案文件创建自定义 API

注意

这是一个高级主题，假定你已阅读并理解以下主题：

• 创建和使用自定义 API
• 使用插件注册工具创建自定义 API

本文演示如何通过将定义文件添加到Microsoft Dataverse解决方案项目来创建自定义 API。 此方法适用于将 解决方案文件存储在源代码管理中的解决方案 发布者并应用应用程序生命周期管理（ALM）做法的解决方案发布者。

使用 Microsoft Power Platform CLI 初始化解决方案项目、生成解决方案包并将其导入 Dataverse 环境。 无需先创建或导出空解决方案。

先决条件

• 安装 Microsoft Power Platform CLI。
• 安装包含命令的 .NET SDKdotnet。
• 有权访问有权导入解决方案的 Dataverse 环境。

步骤 1：初始化解决方案项目

从要在其中创建项目的文件夹运行以下命令：

pac solution init --publisher-name Samples --publisher-prefix sample --outputDirectory CustomAPIExample

pac solution init 命令创建一个CustomAPIExample包含：

• CustomAPIExample.cdsproj：Dataverse 解决方案项目文件。
• src\Other\Solution.xml：解决方案和发布者定义。
• src\Other\Customizations.xml：解决方案自定义定义。
• src\Other\Relationships.xml：解决方案关系定义。

输出目录名称将成为解决方案唯一名称。 在继续之前验证 src\Other\Solution.xml 生成的值。

注意

发布者名称和自定义前缀必须满足 pac 解决方案 init 中所述的要求。 在目标环境中或要创建的新发布者使用现有发布服务器的值。

步骤 2：添加自定义 API 的定义

解决方案中的所有自定义 API 都位于名为 customapis 的文件夹内。 在该文件夹中，每个自定义 API 都位于一个名为自定义 API UniqueName 属性的文件夹中。 表示自定义 API 的数据位于名为 的 XML 文件中。

1. 在文件夹中，创建一个名为 > 的新文件夹。

2. 在 customapis 文件夹中，使用 UniqueName 要创建的自定义 API 创建文件夹。 在本示例中，我们使用 sample_CustomAPIExample。

3. 在创建的 sample_CustomAPIExample 文件夹中，创建一个名为 . customapi.xml.

4. 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。

若要检索 PluginTypeExportKey 和 PluginTypeId 值，请在知道插件类型的名称时使用 Web API 查询：

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

步骤 3：添加任何自定义 API 请求参数

在名为 <a0/> 的文件夹中包含自定义 API 的请求参数的定义。 在该文件夹中，每个自定义 API 请求参数都位于一个名为其 UniqueName 属性的文件夹中。

1. 如果自定义 API 具有任何请求参数，请在该文件夹中创建名为 <a0/> 的文件夹。

2. 对于每个自定义 API 请求参数，请使用 UniqueName 自定义 API 请求参数的属性创建新文件夹。 在本示例中，我们使用 StringParameter。

3. 在该文件夹中，添加一个名为 customapirequestparameter.xml..

4. 编辑 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>
   

   请参阅 自定义 API 请求参数表列 来设置元素的值。

步骤 4：添加任何自定义 API 响应属性

在名为 <a0/a0> 的文件夹中定义自定义 API 的响应属性。 每个自定义 API 响应属性都驻留在其自己的文件夹中，该文件夹以属性 UniqueName 的值命名。

1. 如果自定义 API 包含响应属性，请在其中CustomAPIExample\src\customapis\sample_CustomAPIExample创建一个customapiresponseproperties文件夹。

2. 对于每个自定义 API 响应属性，请使用 UniqueName 自定义 API 响应属性的属性创建新文件夹。 在本示例中，我们使用 StringProperty。

3. 添加一 customapiresponseproperty.xml 个名为文件夹的 XML 文件。

4. 编辑 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>
   

   若要设置元素的值，请参阅 自定义 API 响应属性表列。

注意

虽然请求参数和响应属性的架构非常相似，但请注意 isoptional ，对于响应属性无效，在尝试导入解决方案时会导致错误。

步骤 5：查看解决方案项目结构

解决方案项目应具有以下结构：

CustomAPIExample
|   CustomAPIExample.cdsproj
|
\---src
    +---customapis
    |   \---sample_CustomAPIExample
    |       |   customapi.xml
    |       |
    |       +---customapirequestparameters
    |       |   \---StringParameter
    |       |           customapirequestparameter.xml
    |       |
    |       \---customapiresponseproperties
    |           \---StringProperty
    |                   customapiresponseproperty.xml
    |
    \---Other
            Customizations.xml
            Relationships.xml
            Solution.xml

步骤 6：生成解决方案

CustomAPIExample在项目文件夹中，运行：

dotnet build

生成过程将还原所需的包，并在以下位置 bin\Debug\CustomAPIExample.zip创建非托管解决方案包。

步骤 7：导入解决方案

重要

需要对 Dataverse 环境进行经过身份验证的 PAC CLI 会话。

如果已有身份验证配置文件，请使用 pac 身份验证列表和 pac 身份验证选择 来选择目标环境的配置文件。

如果没有任何身份验证配置文件， 请了解如何连接到环境。

1. CustomAPIExample从项目文件夹中导入并发布解决方案：

   pac solution import --path .\bin\Debug\CustomAPIExample.zip --publish-changes
   

等待导入完成。

注意

如果同时安装另一个解决方案，则可能会出现错误。 有关详细信息，请参阅 并发解决方案操作失败。 解决方法通常是稍后重试。

步骤 8：验证是否已将自定义 API 添加到解决方案

在Power Apps中，打开 CustomAPIExample 解决方案，并验证是否包含自定义 API 以及关联的请求参数和响应属性。

此时，可以使用 测试自定义 API 中所述的步骤测试 API。 此时，可以使用 测试自定义 API 中所述的步骤测试 API。

更新解决方案中的自定义 API

寄送包含自定义 API 的解决方案后，可能需要对非托管解决方案中的自定义 API 进行一些更改。 可以添加新的参数或响应属性，并更改支持更新的列，例如 displayname 和 description。

在生成和导入更新的解决方案之前，请将修订设置为大于已安装的版本的值。 例如，从解决方案项目文件夹运行以下命令：

pac solution version --revisionversion 2 --solutionPath .\src
dotnet build
pac solution import --path .\bin\Debug\CustomAPIExample.zip --publish-changes

重要

不能在解决方案中引入对自定义 API 的更改，该 API 修改保存后无法更改的任何属性。 安装包含自定义 API 定义的解决方案的较新版本时，它将尝试更新自定义 API、自定义 API 请求参数和自定义 API 响应属性。 解决方案更新与尝试使用任何其他方法更新自定义 API 相同。

以下是创建自定义 API 后无法更改的解决方案文件中的属性：

• 自定义 API 属性：
  • allowedcustomprocessingsteptype
  • bindingtype
  • boundentitylogicalname
  • isfunction
  • uniquename
  • workflowsdkstepenabled
• 自定义 API 请求参数属性：
  • isoptional
  • logicalentityname
  • type
  • uniquename
• 自定义 API 响应属性属性：
  • logicalentityname
  • type
  • uniquename

有关详细信息，请参阅 CustomAPI 表。 有关详细信息，请参阅 CustomAPI 表。

使用解决方案提供本地化标签

可以直接在自定义 API 实体的解决方案文件中提供翻译，而不是使用 本地化标签值中所述的过程。 例如，如果要为自定义 API 提供日语本地化标签，则可以为 description 自定义 API 提供它们和 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
• 创建自己的邮件
• Microsoft Power Platform CLI 解决方案命令组