Crear una API personalizada con archivos de solución

Nota

Este es un tema avanzado que asume que ya ha leído y comprendido estos temas:

• Crear y usar API personalizadas
• Cree una API personalizada con la herramienta de registro de complementos

En este artículo se muestra cómo crear una API personalizada agregando archivos de definición a un proyecto de solución de Microsoft Dataverse. Este enfoque es útil para los editores de soluciones que almacenan archivos de solución en el control de código fuente y aplican prácticas de administración del ciclo de vida de las aplicaciones (ALM).

Use Microsoft Power Platform CLI para inicializar el proyecto de solución, compilar el paquete de solución e importarlo en un entorno de Dataverse. No es necesario crear ni exportar primero una solución vacía.

Prerequisites

• Instale Microsoft Power Platform CLI.
• Instale un SDK de .NET que incluya el dotnet comando .
• Tener acceso a un entorno de Dataverse donde tiene privilegios para importar soluciones.

Paso 1: Inicialización de un proyecto de solución

En la carpeta donde desea crear el proyecto, ejecute el siguiente comando:

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

El comando pac solution init crea una CustomAPIExample carpeta que contiene:

• CustomAPIExample.cdsproj: archivo de proyecto de solución de Dataverse.
• src\Other\Solution.xml: la solución y la definición del publicador.
• src\Other\Customizations.xml: definición de personalizaciones de la solución.
• src\Other\Relationships.xml: definición de relaciones de solución.

El nombre del directorio de salida se convierte en el nombre único de la solución. Compruebe los valores generados en src\Other\Solution.xml antes de continuar.

Nota

El nombre del publicador y el prefijo de personalización deben cumplir los requisitos descritos para la inicialización de la solución pac. Use valores para un publicador existente en el entorno de destino o un nuevo publicador que quiera crear.

Paso 2: Adición de la definición de la API personalizada

Todas las API personalizadas de una solución se encuentran dentro de una carpeta llamada customapis. Dentro de esa carpeta, cada API personalizada se encuentra en una carpeta denominada después de la propiedad de API UniqueName personalizada. Los datos que representan la API personalizada se encuentra en un archivo XML denominado customapi.xml.

1. En la CustomAPIExample\src carpeta , cree una carpeta denominada customapis.

2. En la carpeta customapis, cree una carpeta con el UniqueName de la API personalizada que desea crear. En este ejemplo, usamos sample_CustomAPIExample.

3. En la carpeta sample_CustomAPIExample que creó, cree un archivo llamado customapi.xml.

4. Edite customapi.xml para establecer las propiedades de la API personalizada que desea crear. En este ejemplo, use el siguiente 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>
   

   Consulte la información de Columnas de tabla de API personalizadas para establecer los valores de los elementos.

Establecer una relación con un tipo de complemento (opcional)

Si ya tiene un tipo de complemento que desea asociar a esta API personalizada, incluya una referencia a ella en esta definición agregando el siguiente elemento dentro del <customapi> elemento :

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

o

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

Nota

Cualquier valor funcionará, pero le recomendamos que utilice plugintypeexportkey.

Para recuperar los valores PluginTypeExportKey y PluginTypeId , use una consulta de API web cuando conozca el nombre del tipo de complemento:

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

Paso 3: Adición de parámetros de solicitud de API personalizados

Incluya definiciones de parámetros de solicitud para la API personalizada en una carpeta denominada customapirequestparameters. Dentro de esa carpeta, cada parámetro de solicitud de API personalizado se encuentra en una carpeta denominada después de su UniqueName propiedad.

1. Si la API personalizada tiene parámetros de solicitud, en la CustomAPIExample\src\customapis\sample_CustomAPIExample carpeta , cree una carpeta denominada customapirequestparameters.

2. Para cada parámetro de solicitud de API personalizada, cree una nueva carpeta utilizando la propiedad UniqueName del parámetro de solicitud de API personalizada. En este ejemplo, usamos StringParameter.

3. En la carpeta , agregue un archivo XML denominado customapirequestparameter.xml.

4. Edite el archivo customapirequestparameter.xml para establecer las propiedades de la API personalizada que desea crear. En este ejemplo, usamos lo siguiente:

   <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>
   

   Consulte Columnas de tabla de parámetros de solicitud de API personalizada para establecer los valores de los elementos.

Paso 4: Agregar cualquier propiedad de respuesta de API personalizada

Las propiedades de respuesta se definen para la API personalizada en una carpeta denominada customapiresponseproperties. Cada propiedad de respuesta de API personalizada reside en su propia carpeta, que se denomina después del valor de UniqueName la propiedad.

1. Si la API personalizada incluye propiedades de respuesta, cree una customapiresponseproperties carpeta dentro de CustomAPIExample\src\customapis\sample_CustomAPIExample.

2. Para cada propiedad de respuesta de la API personalizada, cree una nueva carpeta utilizando la propiedad UniqueName de la propiedad de respuesta de la API personalizada. En este ejemplo, usamos StringProperty.

3. Agregue un archivo XML denominado customapiresponseproperty.xml a la carpeta .

4. Edite el archivo customapiresponseproperty.xml para establecer las propiedades de la API personalizada que desea crear. En este ejemplo, usamos lo siguiente:

   <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>
   

   Para establecer los valores de los elementos, consulte Columnas de tabla de propiedades de respuesta de API personalizadas.

Nota

Si bien el esquema para los parámetros de solicitud y las propiedades de respuesta es muy similar, tenga en cuenta que isoptional no es válido para una propiedad de respuesta y provocará un error cuando intente importar la solución.

Paso 5: Revisión de la estructura del proyecto de solución

El proyecto de solución debe tener esta estructura:

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

Paso 6: Compilación de la solución

En la carpeta del CustomAPIExample proyecto, ejecute:

dotnet build

El proceso de compilación restaura los paquetes necesarios y crea el paquete de solución no administrado en bin\Debug\CustomAPIExample.zip.

Paso 7: Importación de la solución

Importante

Necesita una sesión de la CLI de PAC autenticada en el entorno de Dataverse.

Si ya tiene perfiles de autenticación, use la lista de autenticación de pac y la autenticación de pac seleccione para seleccionar el perfil para el entorno de destino.

Si no tiene perfiles de autenticación, aprenda a conectarse a su entorno.

1. En la carpeta del CustomAPIExample proyecto, importe y publique la solución:

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

Espere a que termine la importación.

Nota

Es posible que vea un error si se instala otra solución al mismo tiempo. Para obtener más información, consulte Errores simultáneos de la operación de solución. Normalmente, la resolución es intentarlo de nuevo más tarde.

Paso 8: verificar que la API personalizada se agregó a su solución

En Power Apps, abra la solución CustomAPIExample y compruebe que se incluyen la API personalizada y los parámetros de solicitud y las propiedades de respuesta asociadas.

En este momento, puede probar la API mediante los pasos descritos en Prueba de la API personalizada. En este momento, puede probar la API mediante los pasos descritos en Prueba de la API personalizada.

Actualizar una API personalizada en una solución

Después de enviar una solución que contiene una API personalizada, es posible que desee realizar algunos cambios en la API personalizada de la solución no administrada. Puede agregar nuevos parámetros o propiedades de respuesta y realizar cambios en aquellas columnas que admiten su actualización, como displayname y description.

Antes de compilar e importar una solución actualizada, establezca la revisión en un valor mayor que la versión que ya está instalada. Por ejemplo, ejecute estos comandos desde la carpeta del proyecto de solución:

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

Importante

No puede introducir cambios en API personalizadas en una solución que modifique cualquiera de las propiedades que no se pueden cambiar después de guardarse. Cuando instale una versión más reciente de una solución que contenga una definición de API personalizada, intentará actualizar las propiedades de API personalizada, de los parámetros de solicitud de API personalizados y de respuesta de API personalizada. Una actualización de la solución es lo mismo que intentar actualizar la API personalizada utilizando cualquier otro método.

Las siguientes se indican propiedades en los archivos de la solución que no se pueden cambiar después de crear una API personalizada:

• Propiedades de API personalizadas:
  • allowedcustomprocessingsteptype
  • bindingtype
  • boundentitylogicalname
  • isfunction
  • uniquename
  • workflowsdkstepenabled
• Propiedades del parámetro de solicitud de API personalizada:
  • isoptional
  • logicalentityname
  • type
  • uniquename
• Propiedades de propiedad de respuesta de API personalizadas:
  • logicalentityname
  • type
  • uniquename

Para obtener más información, consulte Tablas customAPI. Para obtener más información, consulte Tablas customAPI.

Proporcionar etiquetas localizadas con la solución

En lugar de usar el proceso descrito en Valores de etiqueta localizada, puede proporcionar traducciones directamente en los archivos de solución para entidades de API personalizadas. Por ejemplo, si desea proporcionar etiquetas localizadas en japonés para la API personalizada, puede proporcionarlas para las description propiedades y displayname , como se muestra en el ejemplo siguiente:

<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>

Consulte también

• Crear y usar API personalizadas
• Tablas CustomAPI
• Cree una API personalizada con la herramienta de registro de complementos
• Crear una API personalizada en Power Apps
• Crear una API personalizada con código
• Crear sus propios mensajes
• grupo de comandos de la CLI de Microsoft Power Platform