Criar e usar APIs personalizadas

Use APIs personalizadas para criar suas próprias APIs no Dataverse. Você pode consolidar uma ou mais operações em uma API personalizada que você e outros desenvolvedores podem chamar em seu código ou no Power Automate. O conector do Microsoft Dataverse permite ações de chamada no Power Automate.

Você pode usar a API personalizada como eventos de negócios para habilitar a criação de novos recursos de integração, como expor um novo tipo de evento de gatilho no conector do Microsoft Dataverse. Saiba mais sobre os eventos de negócios do Microsoft Dataverse.

As APIs personalizadas são uma alternativa às ações personalizadas de processo. As ações de processo personalizado fornecem uma maneira sem código de incluir mensagens personalizadas, mas têm algumas limitações para os desenvolvedores. As APIs personalizadas fornecem recursos especificamente para os desenvolvedores definirem sua lógica no código com mais opções. Para obter uma comparação completa da ação de processo personalizado e da API personalizada, consulte Comparar a ação de processo personalizado e a API personalizada.

Criar uma API personalizada

Uma API personalizada geralmente inclui a lógica implementada com um plug-in, mas não é necessária. Usando eventos de negócios do Microsoft Dataverse, você pode criar uma API personalizada sem um plug-in para passar dados sobre um evento ao qual outros assinantes respondem.

Na maioria das vezes, você combina uma API personalizada com um plug-in para definir alguma operação delegada ao Dataverse para calcular e retornar o resultado.

Você pode criar uma API personalizada de várias maneiras diferentes:

Customização de API

Ao criar uma API personalizada e parâmetros de solicitação relacionados e propriedades de resposta, entenda que essas definições de API são personalizáveis por padrão. Se eles forem personalizáveis, você poderá iterar e fazer alterações nesses itens em sua solução não gerenciada.

Definir é personalizável como false

No Power Apps, defina a propriedade gerenciada É Personalizável da solução.

Defina essa propriedade para cada API personalizada, parâmetro de solicitação e propriedade de resposta individualmente.

Saiba mais sobre as propriedades gerenciadas.

Adicionar mais parâmetros de solicitação e propriedades de resposta

Mesmo quando você define a propriedade gerenciada É Personalizável para false, você pode adicionar novos parâmetros de solicitação e propriedades de resposta à sua API personalizada. No entanto, as pessoas que adicionam esses parâmetros de solicitação não podem torná-los necessários. Se você optar por permitir etapas de processamento personalizadas em sua API personalizada, outros plug-ins registrados para a mensagem criada pela API personalizada poderão usá-los. Como os parâmetros de solicitação personalizados são opcionais, o plug-in que você fornece para a operação principal da API personalizada pode ignorá-los e não é responsável por usar parâmetros de solicitação personalizados ou definir quaisquer propriedades de resposta personalizadas adicionadas à API personalizada especificada.

Tabelas e entidades de API personalizadas

Para obter informações sobre as tabelas e os valores de coluna a serem usados ao criar APIs personalizadas, consulte tabelas CustomAPI.

Selecionar um tipo de etapa de processamento personalizado

A tabela a seguir descreve qual tipo de etapa de processamento personalizado da API personalizada (AllowedCustomProcessingStepType) usar.

Selecionar um tipo de associação

Associação é um conceito OData que associa uma operação a uma tabela específica. A tabela a seguir descreve o Tipo de Associação de API personalizado (BindingType) que você deve usar.

Selecionar Entity ou EntityCollection requer que você use o nome totalmente qualificado da Função ou Ação ao usar a API Web. O nome totalmente qualificado é Microsoft.Dynamics.CRM.<UniqueName of the custom API>.

Quando você seleciona Entity, um parâmetro de solicitação nomeado Target com o tipo EntityReference é criado automaticamente. Você não precisa criá-lo. Esse valor é passado para todos os plug-ins registrados para esta mensagem.

Quando você seleciona EntityCollection, nenhuma propriedade de parâmetro ou resposta que represente a coleção de entidades é incluída. Definir esse vínculo simplesmente adiciona o requisito de que a operação seja invocada como adição ao conjunto de entidades ao usar a API Web.

Mais informações:

• Ações associadas a uma tabela
• Ações associadas a uma coleção de tabelas
• Funções vinculadas

Quando criar uma função

A propriedade API personalizada É Função controla se a API personalizada é uma função ou ação. No OData, uma função é uma operação que você chama usando uma solicitação HTTP GET . Ele retorna dados sem fazer alterações. Usando uma solicitação GET , você passa todos os parâmetros na URL quando invoca a função.

Você pode testar GET solicitações com mais facilidade usando seu navegador sozinho, mas há um limite de 32 KB (32.768 caracteres) para o comprimento da URL que você pode enviar. Se a API personalizada tiver muitos parâmetros de solicitação complexos que podem fazer com que o comprimento da URL seja muito longo, é aceitável criar uma Ação que execute a mesma operação e passe todos os dados de parâmetro no corpo usando uma POST solicitação.

Saiba como usar funções de API Web

Quando tornar sua API personalizada privada

Por padrão, outros desenvolvedores podem descobrir e usar qualquer API personalizada que você criar. Como o editor de API personalizado, você é responsável por manter as APIs públicas criadas. Não remova sua API nem aplique alterações que interrompa outros consumidores.

Se você não estiver disposto a dar suporte a outros desenvolvedores usando sua API personalizada, defina a propriedade API Personalizada É Privada (IsPrivate) como true antes de enviar a solução gerenciada que contém sua API personalizada.

A propriedade Is Private impede que a API personalizada apareça no documento de serviço $metadata e impede que as ferramentas de geração de código do Dataverse criem classes para usar as mensagens para sua API personalizada.

Definir essa propriedade não significa que outros desenvolvedores não poderão usar sua mensagem se souberem e puderem compor uma solicitação para usá-la. Definir a propriedade Is Private indica que você não dá suporte a outros desenvolvedores usando sua mensagem.

Talvez você queira manter uma API personalizada privada até ter certeza de que não precisará removê-la ou introduzir alguma alteração significativa.

Leave Is Private é definido como false em seu ambiente de desenvolvimento para que você possa ver a saída no documento de serviço $metadata ou gerar classes para seu próprio uso. No entanto, definir É Privado como true antes de enviar a API personalizada em sua solução gerenciada.

Mais informações:

• Documento de $metadata do CSDL
• Gerar classes associadas antecipadamente para o SDK para .NET
• Mensagens privadas

Proteger sua API personalizada exigindo um privilégio

Defina a propriedade API personalizada Execute Privilege Name (ExecutePrivilegeName) como o nome do privilégio a ser necessário. Atualmente, não há nenhuma maneira compatível para desenvolvedores fora da Microsoft criarem novos privilégios, mas você pode usar um privilégio existente. Para obter mais informações, consulte P: Posso criar um novo privilégio para minha API personalizada?

Usar um plug-in para incluir lógica em sua API personalizada

Se você não definir o tipo de plug-in de API personalizado (PluginTypeId) para especificar a lógica de operação principal, os usuários ainda poderão invocar a API personalizada.

Você pode optar por não incluir nenhuma lógica no plug-in porque está usando a API personalizada como um evento de negócios. Saiba mais sobre os eventos de negócios do Microsoft Dataverse.

Talvez você não queira adicionar um plug-in como uma etapa de teste. Sem um plug-in, os valores de parâmetro de saída retornam os valores padrão para o tipo porque não há código para defini-los. Caso contrário, consulte Gravar um plug-in para sua API personalizada.

Usar uma API personalizada em um fluxo de trabalho

Defina a API personalizada Habilitada para Fluxo de Trabalho (WorkflowSdkStepEnabled) como true quando você precisar habilitar a chamada de uma API personalizada como uma ação de fluxo de trabalho. No entanto, essa opção adiciona as seguintes limitações para que a API personalizada possa ser chamada no designer de fluxo de trabalho:

• A API personalizada não pode ser uma função. Is Function deve estar falso.

• A API personalizada só pode ter tipos de propriedade de resposta ou parâmetro de solicitação compatíveis com o fluxo de trabalho:

  • booleano
  • DateTime
  • Decimal
  • EntityReference
    • EntityReference só pode ser usado quando a API personalizada está associada a uma entidade.
  • Flutuar
  • Integer
  • Quantia
  • Lista de seleção
  • String
  • Guid

  Os seguintes tipos de propriedade de solicitação ou de resposta não podem ser usados:

  • Entidade
  • Coleção de entidades
  • StringArray

Invocando APIs personalizadas

Uma API personalizada cria uma nova mensagem que os usuários podem invocar por meio da API Web ou do SDK do Dataverse para .NET, assim como qualquer outra operação.

Invocando APIs personalizadas da API Web

Durante o teste, você pode invocar sua API usando um cliente de API como Postman ou Insomnia. Para configurar um ambiente de Insônia que gere o token de acesso necessário, consulte Usar Insônia com a API Web do Dataverse. Se a API for uma ação, siga as etapas em Usar ações da API Web. Se a API for uma função, siga as etapas em Usar funções de API Web.

Veja os seguintes exemplos:

Ação não associada

Essa ação é chamada myapi_CustomUnboundAPI. Ele tem um único parâmetro de solicitação de cadeia de caracteres chamado InputParameter:

POST [Organization URI]/api/data/v9.1/myapi_CustomUnboundAPI
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

{
  "InputParameter": "Value"
}

Função associada à tabela

Essa função nomeada myapi_CustomBoundAPI está associada à tabela da conta:

GET [Organization URI]/api/v9.1/accounts(ed5d4e42-850c-45b7-8b38-2677545107cc)/Microsoft.Dynamics.CRM.myapi_CustomBoundAPI()
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

Função associada à coleção de tabelas

Essa função nomeada myapi_CustomEntityCollectionBoundAPI está associada à coleção de tabelas de conta:

GET [Organization URI]/api/v9.1/accounts/Microsoft.Dynamics.CRM.myapi_CustomEntityCollectionBoundAPI()
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

Mais informações:

• Use ações API da Web
• Usar funções de API Web

Invocar APIs personalizadas do SDK para .NET

Para invocar sua API personalizada, use o código de vinculação adiantada ou tardia. Use a ferramenta pac modelbuilder build para gerar classes auxiliares de solicitação e resposta que expõem os parâmetros de solicitação e as propriedades de resposta de sua API personalizada. Saiba mais sobre a geração de classes de ligação antecipada do SDK para .NET.

Para o código com limite tardio ou para uma API personalizada que você marca como privada, crie um OrganizationRequest com o nome exclusivo da API personalizada. Adicione parâmetros com nomes que correspondam aos nomes exclusivos das propriedades da solicitação.

As APIs personalizadas associadas à entidade têm uma propriedade de solicitação implícita chamada Target. Defina essa propriedade como um EntityReference do registro para invocar a API.

Você pode acessar as propriedades de resposta dos parâmetros da resposta retornada.

Neste exemplo, uma API personalizada nomeada myapi_EscalateCase é associada à tabela de incidentes para aceitar um registro como o Target parâmetro junto com outro parâmetro de solicitação de valor de conjunto de opções chamado Priority. Ele tem uma propriedade de resposta EntityReference chamada AssignedTo.

var req = new OrganizationRequest("myapi_EscalateCase")
{
  ["Target"] = new EntityReference("incident", guid),
  ["Priority"] = new OptionSetValue(1)
};

var resp = svc.Execute(req);

var newOwner = (EntityReference) resp["AssignedTo"];

Saiba como usar mensagens com o SDK para .NET.

Invocar a API personalizada como uma operação em segundo plano

A lógica a ser executada usando uma operação em segundo plano deve ser definida como uma API personalizada. Saiba como usar operações em segundo plano (versão prévia)

Gravar um plug-in para sua API personalizada

Escrever um plug-in para implementar a operação principal para sua API personalizada não é diferente de desenvolver qualquer outro plug-in. No entanto, não use a ferramenta de Registro de Plug-in para definir uma etapa específica e você não pode especificar dados de configuração para passar para o plug-in.

Você precisa saber as seguintes informações:

• O nome da mensagem.
• Os nomes e tipos dos parâmetros de solicitação e das propriedades de resposta.

Os valores de parâmetro de solicitação são incluídos nos InputParameters.

Defina os valores das propriedades de resposta nos OutputParameters.

O código a seguir é um plug-in simples que inverte os caracteres no StringParameter e retorna o resultado como StringProperty.

using System;
using System.Linq;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

namespace CustomAPIExamples
{
    public class Sample_CustomAPIExample : IPlugin
    {
        public void Execute(IServiceProvider serviceProvider)
        {
            // Obtain the tracing service
            ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

            // Obtain the execution context from the service provider.  
            IPluginExecutionContext context = (IPluginExecutionContext)
                serviceProvider.GetService(typeof(IPluginExecutionContext));

            if (context.MessageName.Equals("sample_CustomAPIExample") && context.Stage.Equals(30)) {

                try
                {
                    string input = (string)context.InputParameters["StringParameter"];
                    
                    if (!string.IsNullOrEmpty(input)) {
                        //Simply reversing the characters of the string
                        context.OutputParameters["StringProperty"] = new string(input.Reverse().ToArray());
                    }
                }
                catch (Exception ex)
                {
                    tracingService.Trace("Sample_CustomAPIExample: {0}", ex.ToString());
                    throw new InvalidPluginExecutionException("An error occurred in Sample_CustomAPIExample.", ex);
                }
            }
            else
            {
                tracingService.Trace("Sample_CustomAPIExample plug-in is not associated with the expected message or is not registered for the main operation.");
            }
        }
    }
}

Para obter mais informações sobre como escrever plug-ins, consulte Tutorial: Gravar e registrar um plug-in. Você precisa registrar o assembly, mas não precisa registrar uma etapa. Saiba como usar um plug-in para incluir lógica em sua API personalizada.

Veja o exemplo Sample: API personalizada IsSystemAdmin.

Depois de registrar o assembly, certifique-se de adicionar o assembly e quaisquer tipos à sua solução.

Valores de rótulo localizados

AS APIs personalizadas têm rótulos localizáveis. Você pode localizar os valores de rótulo usando as etapas documentadas em Traduzir texto localizável para aplicativos controlados por modelo e tradução de rótulos e cadeias de caracteres de exibição.

Esse processo envolve a exportação de um arquivo que contém os valores de idioma base e inclui uma coluna para cada idioma habilitado. Em seguida, você pode editar os valores no Excel. Depois de concluir o processo para importar as traduções, os rótulos serão incluídos em sua solução.

O exemplo a seguir mostra a edição da planilha do Excel para adicionar traduções em japonês para os valores em inglês.

Definindo valores localizados

Se você preferir definir rótulos localizados no código, em vez de usar o processo manual descrito anteriormente, utilize a mensagem SetLocLabels com a ação SetLocLabels da API Web ou o SDK para .NET SetLocLabelsRequest.

O exemplo a seguir mostra como usar a API Web para definir os rótulos localizados para a displayname propriedade de uma API personalizada.

Pedir:

POST [Organization URI]/api/data/v9.1/SetLocLabels HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json

{
    "EntityMoniker": {
        "@odata.type": "Microsoft.Dynamics.CRM.customapi",
        "customapiid": "86bcd12e-2f30-eb11-a813-000d3a122b89"
    },
    "AttributeName": "displayname",
    "Labels": [
        {
            "Label": "例え",
            "LanguageCode": 1041
        },
        {
            "Label": "Beispiel",
            "LanguageCode": 1031
        },
        {
            "Label": "ejemplo",
            "LanguageCode": 1034
        }
    ]
}

Resposta:

HTTP/1.1 204 No Content

Recuperando valores localizados

Para recuperar os rótulos localizados, utilize a RetrieveLocLabels usando a função RetrieveLocLabels da API Web ou a classe RetrieveLocLabelsRequest do SDK para .NET.

O exemplo a seguir mostra como usar a função RetrieveLocLabels para obter os rótulos da propriedade displayname de uma API personalizada com customapiid de 88602189-183d-4584-ba4b-8b60f0f5b89f.

Pedir:

GET [Organization URI]/api/data/v9.1/RetrieveLocLabels(EntityMoniker=@p1,AttributeName=@p2,IncludeUnpublished=@p3)?
@p1={'@odata.id':'customapis(88602189-183d-4584-ba4b-8b60f0f5b89f)'}&
@p2='displayname'&
@p3=false HTTP/1.1

Resposta:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveLocLabelsResponse",
    "Label": {
        "LocalizedLabels": [
            {
                "Label": "Custom API Example",
                "LanguageCode": 1033,
                "IsManaged": null,
                "MetadataId": null,
                "HasChanged": null
            },
            {
                "Label": "カスタムAPIの例",
                "LanguageCode": 1041,
                "IsManaged": null,
                "MetadataId": null,
                "HasChanged": null
            }
        ],
        "UserLocalizedLabel": {
            "Label": "Custom API Example",
            "LanguageCode": 1033,
            "IsManaged": null,
            "MetadataId": null,
            "HasChanged": null
        }
    }
}

Perguntas frequentes (FAQs)

As seguintes perguntas e respostas podem ajudá-lo:

P: Posso criar um novo privilégio para minha API personalizada?

R: Embora a API personalizada tenha uma propriedade Execute Privilege Name (ExecutePrivilegeName), atualmente não há nenhuma maneira compatível de criar um novo privilégio apenas para essa API. Essa funcionalidade está planejada para uma versão futura. Enquanto isso, use uma das seguintes opções:

• Use um valor Privilege.Name existente.
• Crie uma entidade personalizada e use um dos privilégios criados para essa entidade. Por exemplo, crie uma entidade chamada new_myaction e configure privilégios para as operações de CRUD geradas para ela. Por exemplo: prvCreatenew_myaction. Inclua essa entidade personalizada com a solução que inclui a API personalizada.

P: Posso ativar ou desativar registros de API personalizados?

R: Você não pode. Embora esses registros tenham as colunas status emotivo de status comuns encontradas na maioria das tabelas do Microsoft Dataverse, definir os valores dessas colunas não afeta a disponibilidade da API personalizada, os parâmetros de solicitação ou as propriedades de resposta.

P: Como posso usar minhas mensagens privadas se elas não estiverem incluídas no documento de serviço de $metadata da API Web?

R: Suas mensagens privadas funcionam independentemente de serem anunciadas no documento da CSDL da API Web $metadata ou não. Enquanto você desenvolve sua solução, defina o IsPrivate valor como false. Você pode consultar a $metadata listagem e usar ferramentas de geração de código que dependem destes dados. No entanto, defina o CustomAPI.IsPrivate valor para true antes de enviar sua solução para outras pessoas usarem. Se você decidir posteriormente que deseja dar suporte a outros aplicativos para usar a mensagem, poderá alterar o CustomAPI.IsPrivate valor para false.

Mais informações:

• Quando tornar sua API personalizada privada
• Mensagens privadas
• Mensagens privadas não podem ser usadas em plug-ins

Problemas conhecidos com APIs personalizadas

As APIs personalizadas agora estão disponíveis em geral, mas algumas funcionalidades relacionadas podem mudar.

Não é possível usar o profiler na depuração

Para depurar usando a ferramenta de Registro de Plug-in e a solução de perfilador de plug-in, você precisa selecionar uma etapa específica do plug-in. A implementação do estágio principal para o plug-in não está disponível atualmente na ferramenta de Registro de Plug-in.

Solução alternativa: registre o tipo de plug-in no PostOperation estágio da mensagem criada para a API personalizada.

Mensagens privadas não podem ser usadas em plug-ins

Se você definir sua API personalizada como privada, não poderá usar essa mensagem em um plug-in. Saiba mais sobre mensagens privadas.

Não é possível definir a configuração segura e não segura para o plug-in de operação principal da API personalizada

Você não pode passar a configuração segura ou não segura para o plug-in de operação principal para a API personalizada.

Solução alternativa: em vez de associar o plug-in à API personalizada, registre o plug-in no PostOperation estágio usando a PRT (ferramenta de Registro de Plug-in). Usando essa abordagem, você pode especificar dados de configuração na PostOperation etapa de plug-in, como normalmente faz.

Para usar essa solução alternativa, você deve configurar sua API personalizada para habilitar os tipos de etapa de processamento personalizadoSync e Async ao criar a API personalizada. Você não pode alterar essa configuração depois de criá-la.

Próximas etapas

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

Consulte também

Criar e usar APIs personalizadas
Criar uma API personalizada com código
Criar uma API personalizada com arquivos de solução
Criar suas próprias mensagens
Tabelas de API personalizadas