Criar uma API personalizada usando a ferramenta de registro de plug-in

A PRT (ferramenta de registro de plug-in) inclui um designer para criar a API personalizada. O PRT é um aplicativo cliente do Windows que faz parte das ferramentas de desenvolvedor que você pode baixar do NuGet. Consulte as ferramentas de desenvolvimento do Dataverse para obter informações sobre como baixar essas ferramentas.

Conectar-se usando a ferramenta de Registro de Plug-in

1. Abra a ferramenta de Registro de Plug-in executando o comando PAC CLI pac tool prt.

2. Selecione +Criar nova conexão para se conectar ao seu ambiente do Dataverse.

3. Verifique se o Office 365 está marcado.

4. Se você estiver se conectando usando uma conta da Microsoft diferente de uma que você está usando no momento, selecione Mostrar Avançado e insira suas credenciais. Caso contrário, deixe Entrar como o usuário atual selecionado.

   Observação

   Se sua conta de usuário emprega MFA (autenticação multifator), verifique se a caixa de seleção Mostrar Avançado não está marcada.

5. Se sua conta da Microsoft fornecer acesso a vários ambientes, selecione Exibir lista de organizações disponíveis.

   

6. Selecione Logon.

7. Se você selecionou Exibir lista de organizações disponíveis, selecione a organização à qual deseja se conectar e selecione Logon.

8. Depois de conectado, você verá todos os plug-ins registrados existentes, atividades de fluxo de trabalho personalizadas e provedores de dados.

   

Criar uma API personalizada

No menu Registrar , selecione o comando Registrar nova API Personalizada . Isso abrirá o formulário para criar uma API personalizada.

Use as informações na tabela abaixo para criar a API Personalizada. Para obter mais detalhes, consulte tabela de colunas de API personalizada

Importante

Algumas opções não podem ser alteradas depois de salvar a API personalizada. Certifique-se de entender a finalidade de cada configuração que não pode ser alterada. Se mais tarde você precisar alterar essa configuração, deverá excluir e recriar a API personalizada. Isso também excluirá quaisquer parâmetros de solicitação ou propriedades de resposta associadas a ele.

Etiqueta	Description	Pode ser alterado
Nome de Exibição	Um nome localizável.	Yes
Nome	Um nome amigável e não localizável.	Yes
Solution	Crie uma nova solução ou selecione uma existente. Definir esse valor definirá o prefixo de personalização apropriado para o campo Nome Exclusivo .	Yes
Nome exclusivo	O nome da API personalizada. Esse valor deve conter apenas caracteres alfanuméricos e nenhum espaço. O nome completo inclui o prefixo de personalização determinado selecionando a solução.	No
Descrição	Uma descrição localizável. Para uso quando a mensagem é exposta para ser chamada em um aplicativo. Por exemplo, como uma Dica de Ferramenta.	Yes
Assembly	Optional. Selecione um assembly que contenha um tipo de plug-in que definirá o que a API personalizada faz.	Yes
Plug-in	Optional. Selecione um tipo de plug-in no assembly selecionado. Você pode definir isso mais tarde.	Yes
Tipo de Etapa de Processamento Personalizada Permitido	Quais tipos de etapas de processamento você permitirá. Mais informações: selecionar um tipo de etapa de processamento personalizado	No
Tipo de Associação	Qual tipo de vinculação de entidade. Mais informações: selecionar um tipo de associação	No
Nome Lógico da Entidade Associada	Se você selecionar Tipo de AssociaçãoEntidade ou EntityCollection, deverá inserir o nome lógico da tabela que representa esse tipo.	No
Executar Nome do Privilégio	O nome de um privilégio que controlará se alguém pode usar a API. Esse deve ser um valor de nome válido da tabela Privilege . Mais informações: proteger sua API personalizada exigindo um privilégio	Yes
Função	Se deseja criar uma função. Mais informações: quando criar uma função	No
Private	Se a API personalizada deve ser privada. Mais informações: quando tornar sua API personalizada privada	Yes

Observação

• O designer de API personalizado prt não expõe a propriedade Enabled For Workflow (WorkflowSdkStepEnabled). Se você quiser criar uma API personalizada que funcione para fluxos de trabalho, precisará usar um método diferente.
• O designer de API personalizado PRT não expõe a propriedade gerenciada É Customizável. Você pode definir isso no Power Apps. Mais informações Personalização de API personalizada

Você pode continuar a adicionar parâmetros de solicitação e propriedades de resposta ou salvar a API personalizada e adicioná-las posteriormente.

Criar parâmetros de solicitação

Uma API personalizada não é necessária para ter parâmetros de solicitação. Ao criar uma API personalizada ou ao editar uma existente, você pode criar novos parâmetros de solicitação clicando em + Adicionar Parâmetro de Solicitação. Isso abrirá o formulário Parâmetro .

Use as informações na tabela abaixo para criar o Parâmetro de Solicitação. Para obter mais detalhes, consulte As colunas da tabela CustomAPIRequestParameter

Etiqueta	Description	Pode ser alterado
Nome de Exibição	Nome de exibição localizável.	Yes
Nome	O nome principal do parâmetro de solicitação de API personalizada. Essa convenção de nomenclatura é recomendada para diferenciar esse parâmetro de outras pessoas que compartilham um Nome Exclusivo comum: {Custom API Unique Name}.{Parameter UniqueName}	Yes
Nome exclusivo	Esse será o nome do parâmetro quando você chamar a API personalizada.	No
Tipo	Selecione o tipo do parâmetro. booleano DateTime Decimal Entidade EntityCollection EntityReference Flutuar Integer Quantia Lista de seleção String StringArray Guid	No
Nome da entidade lógica	Quando Entity, EntityCollection ou EntityReference é selecionado como o Tipo, você pode especificar a tabela.	No
Descrição	Descrição localizável.	Yes
É Opcional	Se um valor para o parâmetro é exigido pelo chamador.	No

Criar propriedades de resposta

Uma API personalizada para uma ação não é necessária para ter nenhuma propriedade de resposta. Ao criar uma API personalizada ou ao editar uma existente, você pode criar novas propriedades de resposta clicando em + Adicionar Parâmetro de Resposta. Isso abrirá o formulário Parâmetro .

Use as informações na tabela abaixo para criar a Propriedade de Resposta. Para obter mais detalhes , consulte colunas de tabela CustomAPIResponseProperty

Etiqueta	Description	Pode ser alterado
Nome de Exibição	Nome de exibição localizável.	Yes
Nome	O nome principal da propriedade da resposta da API personalizada. Essa convenção de nomenclatura é recomendada para diferenciar esse parâmetro de outras pessoas que compartilham um Nome Exclusivo comum: {Custom API Unique Name}.{Property UniqueName}	Yes
Nome exclusivo	Esse será o nome da propriedade retornada quando você chamar a API personalizada.	No
Tipo	Selecione o tipo da propriedade. booleano DateTime Decimal Entidade EntityCollection EntityReference Flutuar Integer Quantia Lista de seleção String StringArray Guid	No
Nome da entidade lógica	Quando Entity ou EntityReference são selecionados como o Tipo, você pode especificar a tabela. Não é possível especificar um Nome de Entidade Lógica ao escolher EntityCollection como o Tipo.	No
Descrição	Descrição localizável.	Yes

Exibir uma lista de API personalizada

Para exibir uma lista de API personalizada, no menu Exibir , selecione o comando Exibir por Mensagem .

Todas as mensagens criadas como API personalizada serão prefixadas pela (API Personalizada).

Excluir API personalizada

Ao exibir uma lista de API personalizada, selecione aquela que você deseja excluir e clique no comando Cancelar registro .

Ou clique com o botão direito do mouse no item e selecione Cancelar registro no menu de contexto.

Atualizar parâmetros de solicitação de API personalizados ou propriedades de resposta

Na lista de parâmetros de solicitação ou propriedades de resposta, selecione esta coluna para editar:

Excluir parâmetros de solicitação de API personalizados ou propriedades de resposta

Na lista de parâmetros de solicitação ou propriedades de resposta, selecione esta coluna para excluir:

Próximas etapas

Se você ainda não definiu a IsPrivate propriedade para sua API personalizada, depois de criar sua API personalizada, poderá recuperar a definição de serviço do documento $metadata CSDL usando uma solicitação GET , mesmo do navegador. Se a URL do seu ambiente for https://yourorg.crm.dynamics.com, você poderá digitar essa URL no campo de endereço do navegador para recuperar o $metadata: https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata.

Pesquise o resultado para localizar o nome da API personalizada e você encontrará a Ação ou Função criada junto com qualquer ComplexType relacionado para representar o valor retornado. Por exemplo:

<ComplexType Name="sample_CustomAPIExampleResponse">
    <Property Name="StringProperty"
        Type="Edm.String"
        Unicode="false"/>
</ComplexType>
<Action Name="sample_CustomAPIExample">
    <Parameter Name="StringParameter"
        Type="Edm.String"
        Nullable="false"
        Unicode="false"/>
    <ReturnType Type="mscrm.sample_CustomAPIExampleResponse"
        Nullable="false"/>
</Action>

Mesmo que você não tenha definido um Plug-in para sua API personalizada, poderá testá-lo para verificar a assinatura. Todas as propriedades de resposta retornarão seus valores padrão porque não há nenhum plug-in para definir os valores. Mais informações: Invocando APIs personalizadas

Se você adicionar um plug-in, deverá escrevê-lo e registrar o assembly. Em seguida, atualize sua API personalizada para definir o Assembly e o Plug-in para especificar qual código executar em resposta à sua API personalizada. Mais informações: escrever um plug-in para sua API personalizada

Consulte também

Criar e usar APIs personalizadas
Criar uma API personalizada no Power Apps
Criar uma API personalizada com código
Criar uma API personalizada com arquivos de solução
Criar suas próprias mensagens
Colunas de tabela de API personalizadas