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

Crie uma API personalizada usando o designer na PRT (ferramenta de registro de plug-in). Este artigo mostra como definir uma API personalizada, adicionar parâmetros de solicitação e propriedades de resposta a ela, e exibi-la, atualizá-la ou excluí-la. O PRT é um aplicativo cliente Windows que faz parte das ferramentas de desenvolvedor que você pode baixar do NuGet. Para obter informações sobre como baixar essas ferramentas, consulte as ferramentas de desenvolvimento do Dataverse.

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 Office 365 está marcada.

  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.

    Note

    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.

    Efetuar login com a ferramenta de registro de plug-in.

  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.

    Exibir plug-ins existentes e atividades de fluxo de trabalho personalizadas.

Criar uma API personalizada

No menu Registrar , selecione o comando Registrar nova API Personalizada . Essa ação abre o formulário para criar uma API personalizada.

Captura de tela do formulário para criar uma API personalizada na ferramenta de registro de plug-in.

Use a tabela a seguir para criar a API personalizada. Para obter mais detalhes, consulte colunas de tabela de API Personalizada.

Importante

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

Rótulo Description Pode ser alterado
Nome de Exibição Um nome localizável. Yes
Nome Um nome amigável e não localizável. Yes
Solução Crie uma nova solução ou selecione uma existente. Definir esse valor define o prefixo de personalização apropriado para o campo Nome Único. 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. Use quando a mensagem estiver disponível para ser chamada em um aplicativo. Por exemplo, como uma Dica de Ferramenta. Yes
Montagem Opcional. Selecione um assembly que contém um tipo de plug-in que define o que a API personalizada faz. Yes
Plug-in Opcional. Selecione um tipo de plug-in no assembly selecionado. Você pode definir esse valor mais tarde. Yes
Tipo de etapa de processamento personalizado permitido Quais tipos de etapas de processamento são permitidos. Mais informações: selecionar um tipo de etapa de processamento personalizado No
Tipo de associação Qual tipo de associação de entidade. Mais informações: selecionar um tipo de associação No
Nome lógico da entidade vinculada Se você selecionar Binding TypeEntity ou EntityCollection, insira o nome lógico da tabela que representa esse tipo. No
Nome do Privilégio de Execução O nome de um privilégio que controla se alguém pode usar a API. Esse nome deve ser um valor válido de Name 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

Note

  • 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, use um método diferente.
  • O designer de API personalizado PRT não expõe a propriedade gerenciada É Customizável. Você pode definir essa propriedade em Power Apps. Para obter mais informações, consulte Personalização da 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 de API personalizados

Uma API personalizada não requer parâmetros de solicitação. Ao criar ou editar uma API personalizada, você pode adicionar parâmetros de solicitação selecionando + Adicionar Parâmetro de Solicitação. Essa seleção abre o formulário Parâmetro .

Captura de tela do formulário Parâmetro usado para criar um parâmetro de solicitação de API personalizado.

Use a tabela a seguir para criar o parâmetro de solicitação. Para obter mais informações, consulte Colunas da tabela CustomAPIRequestParameter.

Rótulo 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. Use esta convenção de nomenclatura para diferenciar esse parâmetro de outros parâmetros que compartilham um Nome Exclusivo comum: {Custom API Unique Name}.{Parameter UniqueName} Yes
Nome Exclusivo O nome do parâmetro quando você chama a API personalizada. No
Tipo Selecione o tipo do parâmetro.
booleano
Data e hora
Decimal
Entidade
ColeçãoDeEntidades
EntityReference
Flutuar
Inteiro
Dinheiro
Lista de separação
Cadeia de caracteres
StringArray
Guid
 No
Nome da entidade lógica Quando você seleciona Entity, EntityCollection ou EntityReference como o Tipo, especifique a tabela. No
Descrição Descrição localizável. Yes
É Opcional Se o chamador deve fornecer um valor para o parâmetro. No

Criar propriedades de resposta de API personalizadas

Uma API personalizada para uma ação não requer nenhuma propriedade de resposta. Ao criar uma API personalizada ou editar uma existente, você pode criar novas propriedades de resposta selecionando + Adicionar Parâmetro de Resposta. Esta seleção abre o formulário Parâmetro.

Captura de tela do formulário Parameter usado para criar uma propriedade de resposta de API personalizada.

Use a tabela a seguir para criar a propriedade de resposta. Para obter mais detalhes, consulte Colunas de Tabela CustomAPIResponseProperty.

Rótulo 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. Use esta convenção de nomenclatura para diferenciar esse parâmetro de outros parâmetros que compartilham um Nome Exclusivo comum: {Custom API Unique Name}.{Property UniqueName} Yes
Nome Exclusivo Esse nome é a propriedade retornada quando você chama a API personalizada. No
Tipo Selecione o tipo da propriedade.
booleano
Data e hora
Decimal
Entidade
ColeçãoDeEntidades
EntityReference
Flutuar
Inteiro
Dinheiro
Lista de separação
Cadeia de caracteres
StringArray
Guid
 No
Nome da entidade lógica Ao selecionar Entity ou EntityReference como o Tipo, especifique a tabela. Você não pode 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 APIs personalizadas

Para exibir uma lista de APIs personalizadas, selecione o comando Exibir por Mensagem no menu Exibir .

Captura de tela do comando Exibição por Mensagem no menu Exibir mostrando APIs personalizadas.

Quaisquer mensagens que você criou como uma API personalizada são prefixadas por (API Personalizada).

Excluir uma API personalizada

Ao exibir uma lista de APIs personalizadas, selecione a API que deseja excluir e selecione Cancelar registro.

Captura de tela do comando Desregistrar usado para excluir uma API personalizada selecionada.

Ou clique com o botão direito do mouse no item e selecione Cancelar o 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 a coluna que você deseja editar:

Captura de tela da coluna usada para editar um parâmetro de solicitação de API personalizado ou uma propriedade de resposta.

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 a coluna que você deseja excluir:

Captura de tela da coluna usada para excluir um parâmetro de solicitação de API personalizado ou uma propriedade de resposta.

Próximas etapas

Se você não definir a propriedade IsPrivate para sua API personalizada, poderá recuperar a definição do serviço depois de criar sua API personalizada. Use uma solicitação GET para obter o documento $metadata CSDL, mesmo do navegador. Se a URL do seu ambiente for https://yourorg.crm.dynamics.com, digite 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. Você encontra 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 se você não definir um Plug-in para sua API personalizada, poderá testá-lo para verificar a assinatura. As propriedades de resposta retornam seus valores padrão porque não há nenhum plug-in para definir os valores. Para obter mais informações, consulte 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. Para obter mais informações, consulte 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

  • Última atualização em