Criar novas APIs

Concluído

Para criar uma nova API no Business Central, você pode criar um objeto Page ou Query. Dependendo do tipo de objeto, defina a propriedade PageType ou QueryType como API. Com os serviços Web OData comuns, você pode publicar uma página ou consulta existente como um serviço Web. Em consequência, todos os campos definidos na página de cartão estarão disponíveis no seu serviço Web. Se você precisar de um campo que não faça parte da página existente, será necessário adicionar esse campo à página, mas aí ele também estará disponível para todos os usuários no aplicativo Business Central.

Com a API, você pode criar páginas separadas que não podem ser solicitadas no aplicativo cliente e só podem ser usadas em chamadas à API. Não é necessário publicar uma página de API, como acontece com serviços Web OData comuns; você só precisa criar uma página de API que faça parte da sua extensão. Uma vez implantada a extensão, a página de API estará disponível.

Para criar uma página de API, use o trecho tpage e defina a propriedade PageType como API. Ao alterar PageType para API, defina também algumas destas propriedades:

• APIVersion: a versão da sua API. Você pode criar várias versões da mesma API. Cada versão é um objeto separado, com seu próprio número de objeto. No entanto, você pode dar suporte a várias versões ao mesmo tempo. Dessa forma, outros serviços que dependem do seu serviço de API não precisam ser modificados diretamente quando o seu serviço adiciona um novo campo ou modifica a estrutura da API. A versão pode ter o valor beta ou v1.0, v1.1, v1.2, v2.0 e assim por diante. Você deve mencionar explicitamente a letra v. Só é possível especificar uma versão principal e uma secundária, não um número de versão de build. Por exemplo, v1.1.3 não é um valor válido.

• APIPublisher: o nome da empresa que criou as APIs. Esse valor é usado na URL para estabelecer conexão com a API e é usado para agrupar todas as APIs do mesmo editor.

• APIGroup: um grupo usado para agrupar diversas APIs logicamente. Esse valor também é usado na URL para estabelecer conexão com a API.

• EntityName: o valor singular da entidade retornada pela API (cliente, item, carro, fornecedor, artista, filme etc.).

• EntitySetName: este parâmetro é o valor plural da entidade retornada pela API (clientes, itens, carros, fornecedores, artistas, filmes etc.).

• DelayedInsert: este valor deve sempre ser definido como true para páginas de API. Essa configuração assegura que os valores só serão inseridos no banco de dados quando todos os valores forem provisionados pela solicitação de API.

• ODataKeyFields: esta propriedade indica qual campo será usado como chave. Ao solicitar um registro específico, você pode definir essa propriedade para indicar qual campo será usado para procurar esse registro em particular. A Microsoft cria um campo SystemId, que está disponível em todas as tabelas, inclusive as suas, sem que você precise criá-lo. O campo SystemId identificará um registro de modo exclusivo e nunca será alterado ao longo do tempo, mesmo que você atualize a chave primária. Recomendamos que você use o campo SystemId como ODataKeyFields.

O exemplo de código a seguir mostra a estrutura de uma página de API personalizada que usa a tabela Customer.

page 50115 "My Custom Customer API"

{
    PageType = API;
    APIVersion = 'v1.0';
    APIPublisher = 'mycompany';
    APIGroup = 'sales';
    EntityName = 'mycustomer';
    EntitySetName = 'mycustomers';
    DelayedInsert = true;
    SourceTable = Customer;
    ODataKeyFields = SystemId;

    layout
    {
        area(Content)
        {
            repeater(GroupName)
            {
                field(id;SystemId)
                {
                    ApplicationArea = All;
                }
                field(name;Name)
                {
                    ApplicationArea = All;
                }
                field(email;"E-Mail")
                {
                    ApplicationArea = All;
                }
            }
        }
    }
}

Os nomes de todos os campos devem ser criados com o camel case (camelCase) e não podem conter caracteres especiais.

A URL dessa API se baseia nas propriedades APIPublisher, APIVersion, APIGroup e EntitySetName.

Base URL: https://api.businesscentral.dynamics.com/v2.0/<tenant>/<environment>

/api/<apipublisher>/<apigroup>/<apiversion>/<entitysetname>

Neste exemplo, o URI seria semelhante ao seguinte.

/api/mycompany/sales/v1.0/mycustomers