Compartir a través de

Crear una API personalizada con archivos de solución

  • Artículo

Nota

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

Si bien puede crear API personalizadas a través de un diseñador o con código, también puede definirlas trabajando con archivos dentro de una solución. El uso de archivos en una solución puede ser la opción preferida para los editores de soluciones que aplican las mejores prácticas recomendadas para Administración del ciclo de vida de aplicaciones (ALM).

Un archivo de solución es un archivo comprimido (zip) que se ha exportado desde una instancia Microsoft Dataverse. El contenido de este archivo se puede extraer y los componentes se pueden registrar en un repositorio de origen. El contenido se puede editar y luego volver a comprimir. Los cambios aplicados a la solución son parte de la solución y se crean cuando se importe la solución.

Nota

Estos procesos suelen estar automatizados con herramientas y procesos que están más allá del alcance de este tema. Este tema se centrará en el escenario simple de crear una API personalizada manipulando manualmente los archivos extraídos en una solución para demostrar cómo se pueden usar los datos de los archivos para crear una API personalizada. Más información : Control de código fuente con archivos de solución

Paso 1: crear una solución no administrada

No debe intentar componer un archivo de solución manualmente. Utilice las herramientas de Power Apps para generar un archivo de solución. Siga los pasos de los siguientes artículos para crear y exportar una solución. La solución no necesita contener ningún componente de solución.

  1. Crear una solución

    Para este ejemplo, la solución se define simplemente así:

    Una solución vacía.

  2. Exportar soluciones

    Para este ejemplo, asegúrese de exportar una solución no administrada. La solución administrada es la predeterminada.

    Opción de seleccionar exportar una solución no administrada.

Puede encontrar el archivo exportado en su carpeta de descargas. Tiene un nombre que dependerá del nombre y versión de la solución, en este caso: CustomAPIExample_1_0_0_2.zip.

Paso 2: extraer el contenido de la solución y actualizar la versión

La solución es un archivo comprimido (zip).

  1. Haga clic con el botón derecho en el archivo y elija Extraer todo... desde el menú contextual.

    Debería ver solo los siguientes tres archivos en la carpeta:

    • [Content_Types].xml
    • customizations.xml
    • solution.xml

  2. Abra el archivo solution.xml y localice el elemento 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>

  3. Actualice el valor en 1. En este ejemplo, es <Version>1.0.0.2</Version>.

  4. Guarde el archivo.

Paso 3: agregue 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 estará en una carpeta con el nombre de la propiedad UniqueName de la API personalizada. Dentro de la carpeta, los datos que representan la API personalizada se encuentran dentro de un archivo XML llamado customapi.xml

  1. En la carpeta con los archivos extraídos, cree una nueva carpeta llamada 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, usaremos lo 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 con esta API personalizada, puede incluir una referencia a él en esta definición agregando el siguiente elemento dentro del elemento <customapi>:

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

Puede recuperar los valores PluginTypeExportKey y PluginTypeId usando una consulta de API web como esta, en la que conoce el nombre del tipo de complemento:

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

Paso 4: agregue cualquier parámetro de solicitud de API personalizado

Todas las definiciones de parámetros de solicitud para la API personalizada se incluyen en una carpeta llamada customapirequestparameters. Dentro de esa carpeta, cada parámetro de solicitud de API personalizada estará en una carpeta con el nombre de la propiedad UniqueName del parámetro de la solicitud de la API personalizada.

  1. Si su API personalizada tiene parámetros de solicitud, dentro de la carpeta para la API personalizada que creó en el paso anterior, cree una carpeta llamada 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. Dentro de la carpeta, agregue un archivo xml llamado 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>

Consute la información en Columnas de tabla de CustomAPIRequestParameter para establecer los valores de los elementos.

Paso 5: agregar propiedades de respuesta de API personalizadas

Todas las definiciones de propiedades de respuesta para la API personalizada se incluyen en una carpeta llamada customapiresponseproperties. Dentro de esa carpeta, cada propiedad de respuesta de API personalizada estará en una carpeta con el nombre de la propiedad de respuesta UniqueName de la API personalizada.

  1. Si su API personalizada tiene propiedades de respuesta, dentro de la carpeta de la API personalizada que creó en el Paso 3: agregar la definición de la API personalizada, cree una carpeta llamada customapiresponseproperties.
  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. Dentro de la carpeta, agregue un archivo xml llamado customapiresponseproperty.xml.
  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>

Consute la información en Columnas de tabla de CustomAPIResponseProperty para establecer los valores de los elementos.

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 6: comprima los archivos para crear un nuevo archivo de solución

  1. Regrese a la carpeta donde extrajo el archivo de solución original en el Paso 2: extraer el contenido de la solución y actualizar la versión

  2. Seleccione todos los archivos extraídos y la carpeta customapis que creó.

    Los archivos de solución seleccionados.

  3. Haga clic con el botón secundario en los archivos seleccionados y elija Enviar a > Carpeta comprimida (en zip).

  4. Puede cambiar el nombre del archivo resultante para que sea el que desee. Para este ejemplo, cámbiele el nombre para que coincida con el archivo de solución exportado original: CustomAPIExample_1_0_0_2.zip.

Paso 7: importar la solución con la definición de su API personalizada

  1. Vuelva a Power Apps y seleccione Soluciones.

  2. Seleccione Importar y siga las instrucciones para seleccionar el archivo de solución que creó en el paso anterior.

    Importar el archivo de solución.

    Nota

    Si ve una advertencia que dice Esta versión del paquete de solución ya está instalada, no debe haber actualizado el elemento de la solution.xml Version como se describe en el Paso 2: extraer el contenido de la solución y actualizar la versión.

  3. Debería aparecerle una advertencia que diga Este paquete de solución contiene una actualización para una solución que ya está instalada. Seleccione Importar para continuar.

  4. Espere unos minutos mientras se completa la importación de la solución.

Nota

Es posible que vea un error si se está instalando otra solución al mismo tiempo. Más información: La instalación o la desinstalación de la solución no se ha podido realizar porque se estaba instalando o desinstalando otra solución al mismo tiempo

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

Abra la solución que creó y verifique que la API personalizada y los parámetros de solicitud asociados y las propiedades de respuesta estén incluidos.

Mostrando que el componente de la solución se instaló correctamente.

En este punto, puede probar su API siguiendo los pasos descritos en Probar 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.

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 RequestParameter de la API personalizada:
    • isoptional
    • logicalentityname
    • type
    • uniquename
  • Propiedades de la propiedad de respuesta de la API personalizada:
    • logicalentityname
    • type
    • uniquename

Más información: Tablas de la API personalizada

Proporcionar etiquetas localizadas con la solución

Como alternativa al proceso descrito en Valores de etiqueta localizados, si está editando los archivos de solución para entidades de API personalizadas, puede proporcionar traducciones directamente en estos archivos. Por ejemplo, si desea proporcionar etiquetas localizadas en japonés para su API personalizada, puede proporcionarlas para las propiedades description y displayname, como se muestra a continuación:

<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

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).