Creazione di nuove API

Completato

Per creare una nuova API in Business Central, è possibile creare un oggetto Pagina o Query. A seconda del tipo di oggetto, impostare la proprietà PageType o QueryType su API. Con i normali servizi Web OData, è possibile pubblicare una pagina o una query esistente come servizio Web. Di conseguenza, tutti i campi definiti nella pagina della scheda sono disponibili nel servizio Web. Se è necessario un campo che non faceva parte della pagina esistente, occorre aggiungerlo alla pagina; questo campo sarà però disponibile anche per tutti gli utenti nell'applicazione Business Central.

Con l'API, è possibile creare pagine separate che non possono essere richieste nell'applicazione client e possono essere utilizzate solo nelle chiamate API. Non è necessario pubblicare una pagina API come si fa con i normali servizi Web OData; occorre solo creare una pagina API che fa parte dell'estensione. Con la distribuzione della propria estensione, la pagina API sarà disponibile.

Per creare una pagina API, usare il frammento tpage e impostare la proprietà PageType su API. Quando si imposta PageType su API, impostare anche alcune delle seguenti proprietà:

• APIVersion: la versione dell'API. È possibile creare più versioni della stessa API. Ogni versione è un oggetto separato, con un numero oggetto specifico. Tuttavia, è possibile supportare più versioni contemporaneamente. In questo modo, altri servizi che si basano sul servizio API non devono essere modificati direttamente quando il servizio aggiunge un nuovo campo o modifica la struttura dell'API. La versione può avere il valore beta o v1.0, v1.1, v1.2, v2.0 e così via. È necessario menzionare esplicitamente la lettera v. È possibile specificare solo una versione principale e secondaria, non un numero di versione della build. Ad esempio, v1.1.3 non è un valore valido.

• APIPublisher: il nome della società che ha creato le API. Questo valore viene usato nell'URL per connettersi all'API e viene usato per raggruppare tutte le API dello stesso editore.

• APIGroup: un gruppo usato per raggruppare logicamente un numero di API. Questo valore viene usato anche nell'URL per connettersi all'API.

• EntityName: il valore singolare dell'entità restituita dall'API (Cliente, Articolo, Auto, Fornitore, Artista, Film e così via).

• EntitySetName: questo parametro è il valore plurale dell'entità restituita dall'API (Clienti, Articoli, Auto, Venditori, Artisti, Film e così via).

• DelayedInsert: questo valore deve essere sempre impostato su true per le pagine API. Questa impostazione garantisce che i valori vengano inseriti nel database solo quando tutti i valori vengono forniti dalla richiesta API.

• ODataKeyFields: questa proprietà indica quale campo verrà usato come chiave. Quando si richiede un record specifico, è possibile impostare questa proprietà per indicare quale campo si userà per cercare quel particolare record. Microsoft crea il campo SystemId, disponibile su ogni tabella, anche su quelle personali, senza doverlo creare in modo autonomo. Il campo SystemId identifica in modo univoco un record e non cambia mai nel tempo, anche se si aggiorna la chiave primaria. Consigliamo di usare il campo SystemId come ODataKeyFields.

L'esempio di codice seguente mostra la struttura di una pagina API personalizzata che usa la tabella Cliente.

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;
                }
            }
        }
    }
}

I nomi di tutti i campi devono essere creati con notazione Camel (camelCase) e non possono contenere caratteri speciali.

L'URL di questa API si basa sulle proprietà APIPublisher, APIVersion, APIGroup ed EntitySetName.

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

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

In questo esempio, l'URI sarà simile a quello seguente.

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