Azioni associate all'API e a OData

Completato

A questo punto si è appreso come leggere i dati esistenti e creare o aggiornare i dati. È possibile eseguire una procedura anche tramite OData. Poiché l'API è basata su OData, è possibile usare la stessa funzionalità sia nei servizi Web API sia in quelli OData v4.

Tuttavia, in una pagina API non è possibile eseguire alcuna procedura. In una procedura è possibile aggiungere un attributo [ServiceEnabled] usando WebServiceActionContext e WebServiceActionResultCode per impostare il risultato della funzione.

Per implementare questa funzione, aggiungere il nome della funzione all'URL. Nei servizi API e in quelli OData v4, l'URL per le azioni associate è leggermente diverso. Con OData si usa NAV. come prefisso. Con l'API si usa invece Microsoft.NAV. come prefisso.

L'URL per OData v4 sarà quindi il seguente:

POST /ODataV4/Company(<companyName>)/Customers(<code>)/NAV.<functionName>

L'URL per l'API sarà invece:

POST /api/v2.0/Company(<companyid>)/customers(<id>)/Microsoft.NAV.<functionName>

L'esempio seguente mostra l'applicazione di un modello a un record cliente durante la creazione del cliente tramite l'API. I modelli dipendono dall'area fornita come parametro. Una codeunit include una parte di logica che consente di recuperare il modello corretto e applicarlo al record del cliente.

[ServiceEnabled]
procedure ApplyTemplate(var actionCnxt: WebServiceActionContext; region: Text[20])
var
    CustomLogicMngt: Codeunit "Custom Logic Management";
begin
    if region = '' then
        Error('You must provide a valid region code for this function.');

    CustomLogicMngt.ApplyCustomerTemplate(Rec, region);
    actionCnxt.SetObjectType(ObjectType::Page);
    actionCnxt.SetObjectId(Page::"My Custom Customer API");
    actionCnxt.AddEntityKey(Rec.FieldNo(SystemId), Rec.SystemId);

    actionCnxt.SetResultCode(WebServiceActionResultCode::Updated);
end;

Nell'enumeratore WebServiceActionResultCode è possibile specificare se un record è stato creato o aggiornato o se la funzione è stata completata e deve restituire un codice di stato HTTP di 200.

Azioni non associate

I servizi Web OData supportano anche Azioni non associate. Queste azioni non associate vengono create in codeunit e non sono collegate a un'entità specifica (quindi Non associate). Le azioni non associate non sono disponibili per i servizi API, ma solo per i servizi Web OData. Una procedura in una codeunit pubblicata come azione non associata non richiede un attributo Servizio abilitato. È sufficiente creare una procedura pubblica e pubblicare la codeunit come servizio Web.

L'URL per l'azione non associate OData v4 sarà quindi il seguente:

POST /ODataV4/{serviceName}_{procedureName}?company={companyName}

codeunit 50100 "MiscOperations"
{
    procedure Ping(input: Integer): Integer
    begin
        exit(-input);
    end;
 
    procedure Delay(delayMilliseconds: Integer)
    begin
        Sleep(delayMilliseconds);
    end;
 
    procedure GetLengthOfStringWithConfirmation(inputJson: Text): Integer
    var
        c: JsonToken;
        input: JsonObject;
    begin
        input.ReadFrom(inputJson);
        if input.Get('confirm', c) and c.AsValue().AsBoolean() = true and input.Get('str', c) then
            exit(StrLen(c.AsValue().AsText()))
        else
            exit(-1);
    end;
}

Se si pubblica la codeunit con un nome di servizio MiscOperations, le procedure saranno disponibili con gli URL seguenti:

POST /ODataV4/MiscOperations_Ping?company=CRONUS%20USA%20Inc.

POST /ODataV4/MiscOperations_Delay?company=CRONUS%20USA%20Inc.

POST /ODataV4/MiscOperations_GetLengthOfStringWithConfirmation?company=CRONUS%20USA%20Inc.