Работа с Microsoft Dynamics CRM Web API

Март 28, 2017 / Автор AlexR / Рубрики Блог, Microsoft Dynamics CRM / Комментировать

С выходом Microsoft Dynamics CRM 2016, добавился новый интерфейс, называемый Web API. Если Вы о нем пока еще ничего не слышали, то вот ссылка на хорошую статью и если Вы еще не используете его, то я очень советую начать это делать.

В данном посте я расскажу о библиотеке, которая поможет создавать веб-ресурсы для CRM или разрабатывать Node.js приложения, с использованием интерфейса Microsoft Dynamics CRM Web API.

Библиотека называется: DynamicsWebApi, и её можно найти на GitHub или загрузить с помощью npm.

npm install dynamics-web-api --save

DynamicsWebApi решает несколько проблем, например: создание правильных запросов к Web API, преобразование результата в JSON объект и так далее. Данные задачи хоть и тривиальны для опытных разработчиков, но скучноваты, так как приходится постоянно повторять один и тот же код, создавая «велосипеды». В целом можно сказать, что цель этой библиотеки ровно такая же, как и SDK.REST.js, написанная Microsoft для обращения к точке доступа OData; или популярного XrmServiceToolkit, который облегчил жизнь CRM разработчиков во всем мире. Данные скрипты, на момент написания статьи, не поддерживают Web API.

Главные достоинства DynamicsWebApi

  • Независимость от других библиотек. Например, как XrmServiceToolkit зависим от jQuery.
  • Можно использовать для написания скриптов для веб-браузера (CRM веб-ресурсы), либо для разработки Node.js приложения, преднозначенного для работы с Microsoft Dynamics CRM (и Dynamics 365).
  • Существует две версии библиотеки: одна использует Promise для асинхронных запросов, вторая — старые-добрые Callbacks, для совместимости с веб-браузерами, которые Promise не поддерживают, например IE.
  • Практически безболезненный переход на DynamicsWebApi в уже написанном коде, который использует, например XMLHttpRequest класс — нужно только заменить запросы, которые станут намного короче и наглядней; результаты данных запросов изменять не нужно.
  • Подробные комментарии к каждому методу и параметру. Если этого не достаточно, проект на GitHub’е содержит детальную документацию по использованию DynamicsWebApi.
  • Сотни тестов, которые покрывают более 90% существующего кода (не покрыты в большей степени только статичные классы, которые не содержат функционала, только константы).
  • Каждый релиз автоматически тестируется с использованием сервиса Travis-CI. Таким образом, если релиз сломан, то он автоматически откатывается.

Примеры запросов с использванием DynamicsWebApi

var dynamicsWebApi = new DynamicsWebApi({ webApiVersion: '8.2' });
var contactRecord = {
    firstname: 'John',
    lastname: 'Doe'
};
dynamicsWebApi.create(contactRecord, 'contacts').then(function(id){
    //можно сделать что-нибудь с возвращенным id
    var propertyToUpdate = {
        firstname: 'Joe';
    }
    return dynamicsWebApi.updateSingleProperty(id, 'contacts', propertyToUpdate, 'return=representation');
}).then(function(contactAfterUpdate)
    if (contactAfterUpdate.firstname === 'Joe'){
        return dynamicsWebApi.deleteRecord(contactAfterUpdate.contactid, 'contacts');
    }
    //еще что-нибудь можно сделать
});
.catch(function(error){
    //здесь можно отловить ошибку при запросе
});

В библиотеке также рализованы запросы к CRM функциям (Functions) и действиям (Actions):

var parameters = {
    LocalizedStandardName: 'Pacific Standard Time',
    LocaleId: 1033
};
dynamicsWebApi.executeUnboundFunction('GetTimeZoneCodeByLocalizedName', parameters)
    .then(function (result) {
        alert(result.TimeZoneCode);
    }).catch(function (error) {
        console.trace(error.message);
    });

Пример с экшеном:

dynamicsWebApi.create({ subject: "test" }, "letters").then(function (letterActivityId) {
    var actionRequest = {
        Target: {
            activityid: letterActivityId,
            "@odata.type": "Microsoft.Dynamics.CRM.letter"
        }
    };
    return dynamicsWebApi.executeBoundAction(queueId, "queues", "Microsoft.Dynamics.CRM.AddToQueue", actionRequest);
}).then(function (response) {
    alert(response.QueueItemId);
}).catch(function (error) {
    console.trace(error.message);
});

Все запросы, которые были сделаны выше, относятся к наиболее часто используемым, и в контексте DynamicsWebApi они называются «простыми». Для того, чтобы делать «непростые» запросы, нужно использовать функции с суффиксом «Request». Один из параметров — это объект «Запрос» (Request) (что и послужило причиной наименования функций таким образом), другой причиной создания отдельных функций было большое количество различных параметров, которые используется в Web API. Их можно было бы все поместить в одну функцию, но тогда код, который бы писался с DynamicsWebApi получился бы совершенно не читаемым, было бы не понятно, какой параметр за что отвечает.

var request = {
    id: '00000000-0000-0000-0000-000000000001',
    collection: 'contacts',
    select: ['firstname', 'lastname', '_parentcustomerid_value'],



    //ETag с хедером If-None-Match указывает, что нужно вернуть данные
    //только если они были изменены с момента создания тэга
    ifnonematch: 'W/"468026"',
    //данный параметр указывает, что нужно включить в результат дополнительные
    //данные, например наименование сущности
    includeAnnotations: 'Microsoft.Dynamics.CRM.lookuplogicalname',
    //запрос делается от лица другого системного пользователя
    impersonate: '00000000-0000-0000-0000-000000000002'
};
dynamicsWebApi.retrieveRequest(request).then(function (response) {
    alert(response.subject);
}).catch(function (error) {
    //если контакт не был найден, то произойдет ошибка
    console.trace(error.message);
});

DynamicsWebApi — это отличная библиотека, которая поможет увеличить скорость написания скриптов для Microsoft Dynamics CRM и Web API, беря на себя все тривиальные функции.
Библиотека DynamicsWebApi полностью совместима с Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016 и Dynamics CRM Online.

Комментарии