Подключение к JSON веб-сервисам Dynamics 365 for Operations • OntargIT

Описание

По сравнению с AX2012, в D365O, была добавлена возможность развертывания JSON веб-сервисов, выполняющих заданную программистом логику. Эти веб-сервисы могут принимать от подключенных к ним клиентов некоторые данные, после чего выполнить работу с таблицами D365O и вернуть результат.

Логика таких веб-сервисов написана на языке X++, но клиентские программы, подлючающиеся к веб-сервису, не зависят от языка программирования, так как они видят только генерируемые при развертывании JSON веб-сервиса страницы, на которых в формате JSON, представляющем собой строку с парами ключ-значение, дается полное описание всех доступных методов веб-сервиса и их переменных.

JSON веб-сервисы имеют две разновидности – одни из них работают с POST запросами, а другие – с GET. POST запросы передают данные в своем теле, храня их в специальной переменной. GET запросы передают данные в строке URL. Развернутые в D365O JSON веб-сервисы работают с POST запросами.

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

В сравнении с SOAP веб-сервисами, описанными в статье «Руководство по подключению к SOAP веб-сервисам Microsoft Dynamics 365 for Operations» , JSON работает быстрее, так как JSON формат описывает данные компактнее чем XML формат, используемый в SOAP.

Вызов веб-сервиса D365O из Desktop приложения

Подготовительный этап

1. Создать новый C# проект.
2. Если нет зарегистрированного приложения в Azure, зарегистрировать его, как описано в статье «Регистрация приложения в Azure»
3. Если в D365O еще не развернут сервис, к которому нужно подключиться, развернуть его, как описано в статье «Развертывание SOAP и JSON веб-сервисов в D365O».
4. Добавить ссылку на проект JsonRequestSender, который описан в статье «Создание вспомогательных классов JsonRequestSender для отправки запросов JSON» .
5. При желании добавить ссылку на пакет System.Runtime.Serialization, как описано в статье «Добавление пакета System.Runtime.Serialization» , если необходима возможность разных названий переменных со стороны сервера и клиента.

Основной код

При использовании вспомогательного проекта JsonRequestSender, вызов JSON веб-сервисов сводится к одной команде. Для этого сначала нужно создать объект класса RequestSender или RequestSender_OAuth.

Так как в вебсервисах D365O используется аутентификация OAuth, нужен класс JsonRequestSender_OAuth.

Copy to Clipboard

Далее, так как JSON вебсервисы D365O используют POST запросы, отправляем POST запрос.

Copy to Clipboard

В метод sendPOSTRequest() передаются два дженерик класса и два аргумента.

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

Первый из аргументов , — это относительный адрес вызываемого метода веб-сервиса в ресурсе. В данном случае вызывается метод createInventJournal веб-сервиса InventJourMovementGeneratorService из группы веб-сервисов InventJourMovementGeneratorServiceGroup, а все JSON веб-сервисы D365O лежат по адресу api/services. Такая структура относительного адреса характерна для D365O, но может быть другой для JSON веб-сервисов развернутых не в D365O. В некоторых случаях относительный адрес может даже быть пустым, если базовый адрес ресурса и есть ссылка на веб-сервис.

Второй аргумент, — это объект контракта с данными, передаваемый в теле POST запроса.

Рассмотрим сигнатуру вызываемого метода веб-сервиса:

Copy to Clipboard

Как видно, для вызова метода нужно 2 аргумента:

1. _inputContracts — список классов контрактов InventJourMovementGeneratorServiceInputContract
2. _dataAreaId – код компании D365O

Оба этих аргумента должны быть переданы внутри единого объекта контракта в теле POST запроса, поэтому необходимо написать класс JSON контракта:

Copy to Clipboard

При этом класс ServiceInputContract, используемый в JsonInputContract представляет собой копию структуры класса InventJourMovementGeneratorServiceInputContract из D365O.

На выходе метода вебсервиса со стороны D365O возвращается класс контракта InventJourMovementGeneratorServiceOutputContract. Как было видно раньше в примере POST запроса, при вызове вебсервиса результат сохраняется в объект контракта JsonOutputContract, который представляет собой копию InventJourMovementGeneratorServiceOutputContract из D365O.

При использовании пакета System.Runtime.Serialization на классы контрактов и их переменные можно добавить аттрибуты [DataContract] и [DataMember], как показано в статье «Добавление пакета System.Runtime.Serialization», для изменения названий переменных по сравнению с их названиями со стороны сервера.

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

Если выходной контракт или вложенные в него контракты клиента не имеют каких-либо компонентов из структуры контрактов сервера, будет выдаваться ошибка, так как вспомогательный класс RequestSender настроен на проверку структуры при преобразовании возвращаемой JSON строки в класс контракта. При желании настройку в RequestSender можно поменять, и тогда на выходе заполнятся только те переменные в контракте клиента, для которых есть переменные в контракте сервера.

Пример

В качестве примера приведено подключение к сервису для создания записи в складском журнале перемещений из статьи «Развертывание SOAP и JSON веб-сервисов в D365O» с помощью приложения Windows forms.

Copy to Clipboard

using System;
using System.Windows.Forms;

namespace InventJourMovementGeneratorServiceJSON
{
    public partial class ServiceConnectorForm : Form
    {
        public ServiceConnectorForm()
        {
            InitializeComponent();
        }

private void generateInventJourButton_Click(
            object sender,
            EventArgs e)
        {
            try
            {
                ServiceInputContract[] inputContracts = ServiceInputContractBuilder.generateInputContractsFromLines(
                    inputTextBox.Text.Split(
                        new string[]
                        {
                            "\r\n",
                            "\n"
                        },
                        StringSplitOptions.None));

this.printOutputTextFromString("Connecting D365O. Please wait...");

ServiceConnector serviceConnector = new ServiceConnector();

JsonOutputContract outputContract = serviceConnector.callService(
                    inputContracts,
                    companyTextBox.Text);

this.printOutputTextFromString(
                    outputContract.InventJournalId != "" ?
                        outputContract.InventJournalId :
                        outputContract.ErrorText);
            }
            catch (Exception ex)
            {
                this.printOutputTextFromString(ex.Message);
            }
        }

private void printOutputTextFromString(string outputText)
        {
            outputTextBox.Clear();

outputTextBox.AppendText(outputText);
        }

private void printOutputTextFromArray(string[] outputTextArray)
        {
            outputTextBox.Clear();

foreach (string outputText in outputTextArray)
            {
                outputTextBox.AppendText(
                    string.Format(
                        "{0}\r\n",
                        outputText));
            }
        }
    }
}

namespace InventJourMovementGeneratorServiceJSON
{
    class JsonInputContract
    {
        public ServiceInputContract[] _inputContracts {get; set;}

public string _dataAreaId {get; set;}
    }
}

using System;

namespace InventJourMovementGeneratorServiceJSON
{
    class ServiceInputContract
    {
        public string ItemId {get; set;}
        public decimal Qty {get; set;}
        public DateTime TransDate {get; set;}
        public string InventLocationId {get; set;}
        public string WMSLocationId {get; set;}
    }
}

using System;

namespace InventJourMovementGeneratorServiceJSON
{
    class JsonOutputContract
    {
        public string InventJournalId {get; set;}

public Int64 InventJournalRecId {get; set;}

public JsonLineOutputContract[] LineOutputContracts {get; set;}

public string ErrorText {get; set;}
    }
}

using System;

namespace InventJourMovementGeneratorServiceJSON
{
    class JsonLineOutputContract
    {
        public Int64 InventJournalLineRecId {get; set;}
    }
}

using System;

namespace InventJourMovementGeneratorServiceJSON
{
    static class ServiceInputContractBuilder
    {
        public static ServiceInputContract[] generateInputContractsFromLines(string[] lines)
        {
            ServiceInputContract[] inputContracts = new ServiceInputContract[lines.Length];

string errorText = "";

for (int i = 0; i < lines.Length; i++)
            {
                try
                {
                    ServiceInputContract inputContract = ServiceInputContractBuilder.generateInputContractFromLine(lines[i]);

inputContracts[i] = inputContract;
                }
                catch (Exception ex)
                {
                    errorText += string.Format(
                        "Error in line {0}. {1}\r\n",
                        i + 1,
                        ex.Message);
                }
            }

if (errorText != "")
            {
                throw new Exception(errorText);
            }

return inputContracts;
        }

public static ServiceInputContract generateInputContractFromLine(string line)
        {
            ServiceInputContract inputContract = new ServiceInputContract();

string[] elements = line.Split(
                new string[]
                {
                    ", "
                },
                StringSplitOptions.None);

if (elements.Length == 5)
            {
                inputContract.ItemId = elements[0];

try
                {
                    decimal qty = decimal.Parse(elements[1]);

if (qty >= 0)
                    {
                        inputContract.Qty = qty;
                    }
                    else
                    {
                        throw new Exception("Quantity must be greater than zero");
                    }
                }
                catch (FormatException)
                {
                    throw new Exception("Quantity must be a number");
                }

try
                {
                    DateTime date = Convert.ToDateTime(elements[2]);

inputContract.TransDate = date;
                }
                catch (FormatException)
                {
                    throw new Exception("Date must be in format: m/d/yyyy");
                }

inputContract.InventLocationId = elements[3];
                inputContract.WMSLocationId = elements[4];
            }
            else
            {
                throw new Exception("Line format must be: Item ID, Quantity, Date, Warehouse, Location");
            }

return inputContract;
        }
    }
}

using JsonRequestSender;

namespace InventJourMovementGeneratorServiceJSON
{
    class ServiceConnector
    {
        public JsonOutputContract callService(
            ServiceInputContract[] inputContracts,
            string company)
        {
            RequestSender_OAuth jsonRequestSender = new RequestSender_OAuth();

return jsonRequestSender.sendPOSTRequest<JsonInputContract, JsonOutputContract>(
                "api/services/InventJourMovementGeneratorServiceGroup/InventJourMovementGeneratorService/createInventJournal",
                this.buildJsonInputContract(
                    inputContracts,
                    company));
        }

private JsonInputContract buildJsonInputContract(
            ServiceInputContract[] inputContracts,
            string company)
        {
            JsonInputContract jsonInputContract = new JsonInputContract();

jsonInputContract._inputContracts = inputContracts;
            jsonInputContract._dataAreaId = company;

return jsonInputContract;
        }
    }
}

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

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

Senior Software Developer, OntargIT

Published On: / Categories: ERP /

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

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

Индустрии

Услуги

Партнеры

Руководство по подключению к JSON веб-сервисам Microsoft Dynamics 365 for Operations

Описание