Развертывание SOAP и JSON веб-сервисов в D365O

Описание

Для создания веб-сервиса, к которому будет подключатся клиентское приложение, как минимум, нужно написать код класса, который описывает логику работы сервиса. Далее по тексту будем называть его классом сервиса. Он содержит в себе методы, которые будут вызываться на стороне клиента.

Но использовать один лишь класс сервиса может быть корректно только в том случае, когда и на входе, и на выходе нам нужно только по одной переменной. Если же на вход метода сервиса подается несколько переменных, то более удобно; а если на выходе метода нужно получить более одной переменной, то единственно возможно, использовать классы контрактов. Эти классы содержат в себе перечень переменных, которые будут приниматься на входе метода или отправляться на выход вместе.

Кроме создания этих классов также нужно создать файлы сервисов, соответствующие созданным классам сервисов, и файлы сервисных групп, объединяющие файлы сервисов, и дающие к ним доступ из клиентского приложения. Доступ дается в виде двух URL ссылок – одна из которых указывает на документ XML, используемый форматом SOAP, а другая на строку JSON, для использования форматом JSON. То есть, веб-сервис D365O разворачивается сразу в двух форматах.

Создание класса контракта

1. Создаем класс с атрибутом [DataContractAttribute].
2. Объявляем переменные, которые в дальнейшем будут вместе поступать на вход или на выход метода сервиса.
3. Для каждой из переменных создаем parm-метод с атрибутом [DataMemberAttribute(««НАЗВАНИЕ ПЕРЕМЕННОЙ»»)]. Под названием переменной имеется в виду имя переменной при обращении к ней на клиентской стороне.
4. Если переменная должна содержать коллекцию вложенных контрактов, то нужно также добавить аттрибут AifCollectionTypeAttribute(“«НАЗВАНИЕ КОЛЛЕКЦИИ»”, Types::Class, classStr(«НАЗВАНИЕ КЛАССА КОНТРАКТА»))], а в качестве возвращаемого типа выбрать List. Если контракт используется как результат, то название коллекции вложенных контрактов должно быть return.

В качестве примера приведен элемент контракта с одной обычной переменной и одной коллекцией вложенных контрактов:

Copy to Clipboard

Создание класса сервиса

1. Создаем обычный класс.
2. Если входные переменные или возвращаемое значение представляют собой массив данных, то, по умолчанию, на стороне клиента они будут восприниматься как тип List, который не всегда работает одинаково в разных языках программирования. Поэтому хорошей практикой считается превращение типов этих переменных в обыкновенные массивы. Делается это с помощью добавления к методам аттрибутов AifCollectionTypeAttribute(“«НАЗВАНИЕ ПЕРЕМЕННОЙ»”, Types:: «ТИП МАССИВА»). При этом в кавычках, в качестве названия переменной, может быть указан return для возвращаемого значения, или название одной из входных переменных метода. В качестве типа массива может быть выбран любой примитивный тип (например, Types::String), или же класс контракта. При указании класса контракта, синтаксис немного изменяется: AifCollectionTypeAttribute(“«НАЗВАНИЕ ПЕРЕМЕННОЙ»”, Types::Class, classStr(«НАЗВАНИЕ КЛАССА КОНТРАКТА»))].

Также он дает возможность добавить аттрибут [DataMember] к их переменным, с опциональным аргументом Name. Например:

Copy to Clipboard

В приведенном примере, в качестве возвращаемого результата со стороны клиента будет массив строк (String[]), а в качестве входной переменной будет приниматься массив классов контрактов (InventoryServiceContract[]). Но при этом в коде D365O, все эти переменные будут рассматриваться и обрабатываться в качестве List, то есть с использованием ListEnumerator для считывания входных данных и метода addEnd() для записи в результирующую переменную.

Кроме того, стоит отметить строку changecompany(“USMF”). При работе с SOAP веб-сервисами, программист со стороны клиента может выбрать нужную ему компанию вызывая веб-сервис, с помощью установки значения в специальную переменную контекста, передаваемую в любой SOAP веб-сервис D365O вместе с входными и выходными переменными. В случае же с JSON веб-сервисами, сменить компанию со стороны клиента по умолчанию невозможно, поэтому нужно учитывать этот момент при написании кода веб-сервиса.

Примеры классов сервиса и контракта

Ниже приведен код сервиса для создания записи в складском журнале перемещений. На вход сервиса идут название компании, в которой нужно создать журнал, а также контракт, содержащий обязательные поля журнала. На выходе сервиса возвращается контракт, содержащий номер и RecId созданного журнала, строку содержащую ошибки, а также коллекцию вложенных контрактов, в которых хранятся RecId созданных строк журналов.

Copy to Clipboard

[DataContractAttribute]
class InventJourMovementGeneratorServiceInputContract
{
    ItemId itemId;

InventQtyJournal qty;

JournalTransDate transDate;

InventLocationId inventLocationId;
    WMSLocationId wmsLocationId;

[DataMemberAttribute("ItemId")]
    public ItemId parmItemId(ItemId _itemId = itemId)
    {
        itemId = _itemId;

return itemId;
    }

[DataMemberAttribute("Qty")]
    public InventQty parmQty(InventQty _qty = qty)
    {
        qty = _qty;

return qty;
    }

[DataMemberAttribute("TransDate")]
    public TransDate parmTransDate(TransDate _transDate = transDate)
    {
        transDate = _transDate;

return transDate;
    }

[DataMemberAttribute("InventLocationId")]
    public InventLocationId parmInventLocationId(InventLocationId _inventLocationId = inventLocationId)
    {
        inventLocationId = _inventLocationId;

return inventLocationId;
    }

[DataMemberAttribute("WMSLocationId")]
    public WMSLocationId parmWMSLocationId(WMSLocationId _wmsLocationId = wmsLocationId)
    {
        wmsLocationId = _wmsLocationId;

return wmsLocationId;
    }

}
[DataContractAttribute]
class InventJourMovementGeneratorServiceOutputContract
{
    InventJournalId inventJournalId;

RefRecId inventJournalRecId;

List lineOutputContracts;

str errorText;

[DataMemberAttribute("InventJournalId")]
    public InventJournalId parmInventJournalId(InventJournalId _inventJournalId = inventJournalId)
    {
        inventJournalId = _inventJournalId;

return inventJournalId;
    }

[DataMemberAttribute("InventJournalRecId")]
    public RefRecId parmInventJournalRecId(RefRecId _inventJournalRecId = inventJournalRecId)
    {
        inventJournalRecId = _inventJournalRecId;

return inventJournalRecId;
    }

[DataMemberAttribute("LineOutputContracts"),
    AifCollectionTypeAttribute(
        "return",
        Types::Class,
        classStr(InventJourMovementGeneratorServiceLineOutputContract))]
    public List parmLineOutputContracts(List _lineOutputContracts = lineOutputContracts)
    {
        lineOutputContracts = _lineOutputContracts;

return lineOutputContracts;
    }

[DataMemberAttribute("ErrorText")]
    public str parmErrorText(str _errorText = errorText)
    {
        errorText = _errorText;

return errorText;
    }

}
[DataContractAttribute]
class InventJourMovementGeneratorServiceLineOutputContract
{
    RefRecId inventJournalLineRecId;

[DataMemberAttribute("InventJournalLineRecId")]
    public RefRecId parmInventJournalLineRecId(RefRecId _inventJournalLineRecId = inventJournalLineRecId)
    {
        inventJournalLineRecId = _inventJournalLineRecId;

return inventJournalLineRecId;
    }

}
class InventJourMovementGeneratorService
{
    [AifCollectionTypeAttribute(
        "_inputContracts",
        Types::Class,
        classStr(InventJourMovementGeneratorServiceInputContract))]
    public InventJourMovementGeneratorServiceOutputContract createInventJournal(
        List _inputContracts,
        DataAreaId _dataAreaId)
    {
        InventJourMovementGeneratorServiceOutputContract outputContract = new InventJourMovementGeneratorServiceOutputContract();

changecompany(_dataAreaId)
        {
            str errorText = this.findInputContractsErrors(_inputContracts);

if (!errorText)
            {
                try
                {
                    ttsbegin;

InventJournalTable inventJournalTable = this.createInventJournalTable(outputContract);

this.createInventJournalLines(
                        inventJournalTable,
                        _inputContracts,
                        outputContract);

ttscommit;
                }
                catch
                {
                    errorText = "Something went wrong during journal generation";
                }
            }

outputContract.parmErrorText(errorText);
        }

return outputContract;
    }

private str findInputContractsErrors(List _inputContracts)
    {
        str errorText = "";

int counter = 0;

ListEnumerator leInputContracts = _inputContracts.getEnumerator();

while (leInputContracts.moveNext())
        {
            counter++;

InventJourMovementGeneratorServiceInputContract inputContract = leInputContracts.current();

if (!InventTable::exist(inputContract.parmItemId()))
            {
                errorText += strFmt(
                    "Error in line %1. Item with ID '%2' doesn't exist in company '%3'\r\n",
                    counter,
                    inputContract.parmItemId(),
                    curExt());
            }

if (!InventLocation::exist(inputContract.parmInventLocationId()))
            {
                errorText += strFmt(
                    "Error in line %1. Warehouse with ID '%2' doesn't exist in company '%3'\r\n",
                    counter,
                    inputContract.parmInventLocationId(),
                    curExt());
            }
            else if (!WMSLocation::exist(
                        inputContract.parmWMSLocationId(),
                        inputContract.parmInventLocationId()))
            {
                errorText += strFmt(
                    "Error in line %1. Location with ID '%2' doesn't exist in warehouse '%3' in company '%4'\r\n",
                    counter,
                    inputContract.parmWMSLocationId(),
                    inputContract.parmInventLocationId(),
                    curExt());
            }
        }

return errorText;
    }

private InventJournalTable createInventJournalTable(InventJourMovementGeneratorServiceOutputContract _outputContract)
    {
        InventJournalTable inventJournalTable;

inventJournalTable.initFromInventJournalName(InventJournalName::find(InventJournalName::standardJournalName(InventJournalType::Movement)));

inventJournalTable.insert();

_outputContract.parmInventJournalId(inventJournalTable.JournalId);
        _outputContract.parmInventJournalRecId(inventJournalTable.RecId);

return inventJournalTable;
    }

private void createInventJournalLines(
        InventJournalTable _inventJournalTable,
        List _inputContracts,
        InventJourMovementGeneratorServiceOutputContract _outputContract)
    {
        List outputLineContracts = new List(Types::Class);

ListEnumerator leInputContracts = _inputContracts.getEnumerator();

while (leInputContracts.moveNext())
        {
            InventJourMovementGeneratorServiceInputContract inputContract = leInputContracts.current();

InventJournalTrans inventJournalTrans;

inventJournalTrans.initFromInventJournalTable(_inventJournalTable);

inventJournalTrans.initFromInventTable(InventTable::find(inputContract.parmItemId()));

inventJournalTrans.Qty = inputContract.parmQty();

inventJournalTrans.TransDate = inputContract.parmTransDate();

InventDim inventDim;

InventLocation inventLocation = InventLocation::find(inputContract.parmInventLocationId());

inventDim.InventSiteId = inventLocation.InventSiteId;
            inventDim.InventLocationId = inventLocation.InventLocationId;

inventDim.WMSLocationId = inputContract.parmWMSLocationId();

inventJournalTrans.InventDimId = InventDim::findOrCreate(inventDim).InventDimId;

inventJournalTrans.insert();

InventJourMovementGeneratorServiceLineOutputContract lineOutputContract = new InventJourMovementGeneratorServiceLineOutputContract();

lineOutputContract.parmInventJournalLineRecId(inventJournalTrans.RecId);

outputLineContracts.addEnd(lineOutputContract);
        }

_outputContract.parmLineOutputContracts(outputLineContracts);
    }

}

Создание файлов сервисов и сервисных групп

1. Создать файл типа Service.

2. Открыть созданый файл и прописать в нем Class и ExternalName. Поле Class должно содержать название созданого ранее класса сервиса. ExternalName можно выбрать любое, — это имя будет видно клиентским приложениям.

3. Нажать правой кнопкой мыши на выпадающем списке Service Operations и выбрать New Service Operation. Выбрав созданую операцию, в ее настройках нужно указать Method и Name. Method должен содержать название одного из методов указаного реннее класса сервиса.

4. Создать файл типа Service Group.

5. В созданный файл мышкой перетянуть созданый ранее файл сервиса, или же нажать правой кнопкой мыши на название группы и выбрать в выпадающем списке New Service. Для добавленного в группу сервиса прописать Name и Service, где Service – это название файла сервиса.

6. Собрать проект.

7. Проверить доступность сервисной группы по ссылке вида https://«ИМЯ ХОСТА»/soap/Services/«НАЗВАНИЕ СЕРВИСНОЙ ГРУППЫ»/?wsdl. Должен выдаться XML документ. Например:

https://oit-adm-boryseda2b5401719f08ddevaos.cloudax.dynamics.com/soap/services/InventJourMovementGeneratorServiceGroup?wsdl

При этом, успешная проверка по ссылке выше, соответствующая адресу SOAP веб-сервиса, также значит и успешное развертывание JSON веб-сервиса, который всегда разворачивается одновременно. JSON веб-сервис доступен по ссылке вида https://«ИМЯ ХОСТА»/api/services/«НАЗВАНИЕ СЕРВИСНОЙ ГРУППЫ»/«НАЗВАНИЕ СЕРВИСА»/«НАЗВАНИЕ МЕТОДА СЕРВИСА». Например:

https://oit-adm-boryseda2b5401719f08ddevaos.cloudax.dynamics.com/api/services/InventJourMovementGeneratorServiceGroup/InventJourMovementGeneratorService/createInventJournal

Подготовил статью:

ДыкухаБорис Александрович

Senior Software Developer, OntargIT

Published On: 21 апреля, 2021 / Рубрики: ERP /

Развивайте бизнес с нами!

OntargIT является официальным партнером Microsoft по внедрению технологий Dynamics 365. С нашим опытом в различных отраслях, мы обеспечим индивидуальный подход и эффективные решения, которые будут идеально соответствовать потребностям вашей компании. Оставьте заявку сейчас, и наша команда экспертов поможет вам воспользоваться всеми преимуществами Dynamics 365.

Отправляя свои данные, я даю согласие на то, чтобы со мной связались

Развивайте бизнес с нами!

Отправляя свои данные, я даю согласие на то, чтобы со мной связались

Индустрии

Услуги

Партнеры

Описание

Создание класса контракта

Создание класса сервиса

Примеры классов сервиса и контракта

Создание файлов сервисов и сервисных групп

Подготовил статью:

Развивайте бизнес с нами!

Развивайте бизнес с нами!

Статус Microsoft Solutions Partner с бизнес-приложений, опыт внедрения и поддержки решений Microsoft Dynamics 365, Power Platform и AI.

Статус Microsoft Solutions Partner с бизнес-приложений, опыт внедрения и поддержки решений Microsoft Dynamics 365, Power Platform и AI.

Индустрии

Услуги

Партнеры

Развертывание SOAP и JSON веб-сервисов в D365O

Описание

Создание класса контракта

Создание класса сервиса

Примеры классов сервиса и контракта

Создание файлов сервисов и сервисных групп

Подготовил статью:

Related Posts

Расширение возможностей CFO благодаря Microsoft Dynamics 365

Цифровая трансформация с Microsoft Dynamics 365

7 шагов для построения плана миграции на SaaS

Развивайте бизнес с нами!

Развивайте бизнес с нами!

Статус Microsoft Solutions Partner с бизнес-приложений, опыт внедрения и поддержки решений Microsoft Dynamics 365, Power Platform и AI.

Статус Microsoft Solutions Partner с бизнес-приложений, опыт внедрения и поддержки решений Microsoft Dynamics 365, Power Platform и AI.