Criar uma API personalizada com arquivos de solução

Este artigo demonstra como criar uma API personalizada adicionando arquivos de definição a um projeto de solução Microsoft Dataverse. Essa abordagem é útil para os editores de soluções que armazenam arquivos de solução no controle do código-fonte e aplicam práticas de ALM (gerenciamento de ciclo de vida do aplicativo).

Use Microsoft Power Platform CLI para inicializar o projeto da solução, criar o pacote de solução e importá-lo para um ambiente do Dataverse. Você não precisa criar ou exportar uma solução vazia primeiro.

Pré-requisitos

• Instale Microsoft Power Platform CLI.
• Instale um SDK .NET que inclua o dotnet comando.
• Tenha acesso a um ambiente do Dataverse em que você tenha privilégios para importar soluções.

Etapa 1: inicializar um projeto de solução

Na pasta em que você deseja criar o projeto, execute o seguinte comando:

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

O comando pac solution init cria uma CustomAPIExample pasta que contém:

• CustomAPIExample.cdsproj: o arquivo de projeto da solução dataverse.
• src\Other\Solution.xml: a solução e a definição do editor.
• src\Other\Customizations.xml: a definição de personalizações de solução.
• src\Other\Relationships.xml: a definição de relações de solução.

O nome do diretório de saída torna-se o nome exclusivo da solução. Verifique os valores gerados src\Other\Solution.xml antes de continuar.

Etapa 2: Adicionar a definição da API personalizada

Todas as APIs personalizadas em uma solução são encontradas em uma pasta chamada customapis. Dentro dessa pasta, cada API personalizada está em uma pasta com o nome da propriedade de API UniqueName personalizada. Os dados que representam a API personalizada estão em um arquivo XML chamado customapi.xml.

1. CustomAPIExample\src Na pasta, crie uma nova pasta chamada customapis.

2. Na pasta customapis , crie uma pasta com a UniqueName API personalizada que você deseja criar. Para este exemplo, usamos sample_CustomAPIExample.

3. Na pasta sample_CustomAPIExample que você criou, crie um arquivo chamado customapi.xml.

4. Edite para customapi.xml definir as propriedades da API personalizada que você deseja criar. Para este exemplo, use o seguinte 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 as informações nas colunas da tabela de API Personalizada para definir os valores dos elementos.

Definir uma relação com um tipo de plug-in (opcional)

Se você já tiver um tipo de plug-in que deseja associar a essa API personalizada, inclua uma referência a ela nesta definição adicionando o seguinte elemento dentro do <customapi> elemento:

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

ou

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

Para recuperar os valores PluginTypeExportKey e PluginTypeId , use uma consulta da API Web quando souber o nome do tipo de plug-in:

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

Etapa 3: adicionar parâmetros de solicitação de API personalizados

Inclua definições de parâmetros de solicitação para a API personalizada em uma pasta chamada customapirequestparameters. Dentro dessa pasta, cada parâmetro de solicitação de API personalizada está em uma pasta com o nome de sua UniqueName propriedade.

1. Se a API personalizada tiver parâmetros de solicitação, na CustomAPIExample\src\customapis\sample_CustomAPIExample pasta, crie uma pasta chamada customapirequestparameters.

2. Para cada parâmetro de solicitação de API personalizado, crie uma nova pasta usando a UniqueName propriedade do Parâmetro de Solicitação de API personalizado. Para este exemplo, usamos StringParameter.

3. Dentro da pasta, adicione um arquivo XML chamado customapirequestparameter.xml.

4. Edite o arquivo customapirequestparameter.xml para definir as propriedades da API personalizada que você deseja criar. Para este exemplo, usamos o seguinte:

   <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 colunas da tabela de parâmetros de solicitação de API personalizada para definir os valores dos elementos.

Etapa 4: Adicionar quaisquer propriedades de resposta de API personalizadas

Você define as propriedades de resposta para a API personalizada em uma pasta chamada customapiresponseproperties. Cada propriedade de resposta de API personalizada reside em sua própria pasta, que tem o nome do valor da UniqueName propriedade.

1. Se a API personalizada incluir propriedades de resposta, crie uma customapiresponseproperties pasta dentro CustomAPIExample\src\customapis\sample_CustomAPIExample.

2. Para cada propriedade de resposta de API personalizada, crie uma nova pasta usando a UniqueName propriedade da Propriedade de Resposta à API personalizada. Para este exemplo, usamos StringProperty.

3. Adicione um arquivo XML nomeado customapiresponseproperty.xml à pasta.

4. Edite o arquivo customapiresponseproperty.xml para definir as propriedades da API personalizada que você deseja criar. Para este exemplo, usamos o seguinte:

   <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 definir os valores dos elementos, consulte colunas da tabela de propriedades de resposta da API personalizada.

Etapa 5: Examinar a estrutura do projeto da solução

Seu projeto de solução deve ter essa estrutura:

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

Etapa 6: Criar a solução

Na pasta do CustomAPIExample projeto, execute:

dotnet build

O processo de build restaura os pacotes necessários e cria o pacote de solução não gerenciado em bin\Debug\CustomAPIExample.zip.

Etapa 7: Importar a solução

Se você já tiver perfis de autenticação, use pac auth list e pac auth select to select the profile for the target environment.

Se você não tiver nenhum perfil de autenticação, aprenda a se conectar ao seu ambiente.

1. Na pasta do CustomAPIExample projeto, importe e publique a solução:

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

Aguarde a importação ser concluída.

Etapa 8: Verificar se a API personalizada foi adicionada à sua solução

Em Power Apps, abra a solução CustomAPIExample e verifique se a API personalizada e as propriedades de resposta e parâmetros de solicitação associados estão incluídos.

Neste ponto, você pode testar sua API usando as etapas descritas em Testar sua API personalizada. Neste ponto, você pode testar sua API usando as etapas descritas em Testar sua API personalizada.

Atualizar uma API personalizada em uma solução

Depois de enviar uma solução que contenha uma API personalizada, talvez você queira fazer algumas alterações na API personalizada em sua solução não gerenciada. Você pode adicionar novos parâmetros ou propriedades de resposta e fazer alterações nas colunas que dão suporte à atualização, como o displayname e description.

Antes de compilar e importar uma solução atualizada, defina a revisão para um valor maior que a versão já instalada. Por exemplo, execute estes comandos na pasta do projeto da solução:

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

Fornecer rótulos localizados com a solução

Em vez de usar o processo descrito em valores de Rótulo Localizado, você pode fornecer traduções diretamente nos arquivos de solução para entidades de API personalizadas. Por exemplo, se você quiser fornecer rótulos localizados em japonês para sua API personalizada, você poderá fornecê-los para as propriedades e displayname as description propriedades, conforme mostrado no exemplo a seguir:

<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 também

• Criar e usar APIs personalizadas
• Tabelas CustomAPI
• Criar uma API personalizada usando a ferramenta de registro de plug-in
• Criar uma API personalizada no Power Apps
• Criar uma API personalizada com código
• Criar suas próprias mensagens
• grupo de comandos da solução da CLI Microsoft Power Platform