top of page
  • Writer's pictureSarov+

Как использовать Custom API в Dynamics CRM: Полное руководство

API creation

В эпоху цифровых инноваций и комплексных бизнес-стратегий, улучшение и расширение возможностей базовых приложений является важным элементом для достижения успеха в деятельности компаний. Custom API от Microsoft в Dataverse — это доступное и простое в использовании решение, которое позволяет компаниям максимально эффективно использовать свои CRM системы. Этот инструмент предоставляет разработчикам и архитекторам удобные и ценные возможности для создания настраиваемых интерфейсов программирования приложений (API) прямо в Dynamics CRM, открывая тем самым новые перспективы в их работе.


Goal of this article

Данная статья рассматривает принципы работы, основные возможности и преимущества использования Custom API в Dataverse. Особое внимание уделяется вопросам интеграции, создания и управления Custom API, а также описываются практические аспекты применения этого инструмента в различных сферах бизнес-процессов. Мы также рассмотрим технические нюансы, связанные с разработкой и внедрением Custom API, и обсудим, как они могут повысить эффективность работы с CRM системами, упростить процессы интеграции с другими приложениями и улучшить общую производительность рабочих процессов.


Цель данной статьи - предоставить читателям глубокое понимание концепции Custom API в Dataverse и показать, как этот инструмент может быть использован для решения конкретных бизнес-задач и улучшения функционала CRM систем.


А узнать больше про Custom API можно в нашем видео:


Что такое Custom API?

This simplifies the process of developing and implementing APIs

Custom API от Microsoft — это продвинутая функция, позволяющая разработчикам создавать и использовать настраиваемые API внутри системы управления клиентскими отношениями (CRM). Основное отличие Custom API от традиционных API заключается в том, что они полностью интегрированы в CRM, избавляя от необходимости их публикации во внешних источниках. Это упрощает процесс разработки и внедрения API, так как устраняет необходимость в обеспечении дополнительной инфраструктуры и управлении доступом.

simplified authorization

Одним из ключевых преимуществ Custom API является упрощенная авторизация. В отличие от традиционных API, где авторизация является важной частью процесса разработки и требует внимательного следования стандартам безопасности, Custom API использует стандартные механизмы авторизации Microsoft. Это значительно облегчает задачу разработчиков, поскольку им не нужно тратить время и ресурсы на разработку собственной системы авторизации.


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


Как создавать Custom API?

How to create a Custom API?

Создание Custom API в Dataverse от Microsoft включает в себя несколько ключевых шагов, каждый из которых играет важную роль в разработке и интеграции API в систему CRM. Вот более подробное описание каждого из этих шагов:


1. Написание Плагина

Writing a Plugin

Процесс начинается с создания плагина. Разработчикам предстоит работать с библиотекой, добавляя новый класс. Важно уделить внимание input параметрам, которые могут варьироваться в зависимости от потребностей. В этом контексте, рекурсия и сложные логические операции, которые может быть сложно реализовать в других средах (например, в Power Flow), могут быть легко интегрированы через Custom API. После написания, плагин компилируется.


2. Регистрация Плагина Через Plugin Registration Tool

Registering a Plugin Using the Plugin Registration Tool

Завершив разработку плагина, следующим шагом является его регистрация. Для этого используется Plugin Registration Tool, где происходит обновление и добавление нового плагина в Dataverse. Важно отметить, что Custom API отличается от Custom Action тем, что не требует дополнительных шагов после регистрации.


3. Ассоциация Плагина и End Point

Plugin and End Point Association

Далее происходит связывание плагина с end point в рамках решения Dataverse. Это включает в себя создание записи для Custom API, указание уникального имени (которое будет являться end point), описание и выбор типа плагина. Эти действия формируют основу для связи между Custom API и разработанным плагином.


4. Создание Input Параметров

Creating Input Parameters

Если для Custom API необходимы input параметры, они создаются на этом этапе. Разработчик должен указать уникальное имя для каждого параметра, а также его тип (например, String, Boolean) и необходимость его использования (обязательный или необязательный).


5. Создание Output Параметров

Creating Output Parameters

Аналогично input параметрам, для Custom API также необходимо создать output параметры. Это включает в себя определение уникальных имен для каждого параметра, их типов и описаний.

unique names for each parameter

Все эти шаги способствуют созданию мощного и гибкого Custom API, который можно эффективно использовать в различных частях системы CRM, обеспечивая более широкие возможности для интеграции и автоматизации бизнес-процессов.


Где мы можем использовать Custom API?

Custom API от Microsoft в Dataverse предоставляет широкие возможности для использования в различных сферах и приложениях. Ниже приведены ключевые области применения Custom API:

Where can we use the Custom API?
  1. Canvas App: Custom API идеально подходит для использования в Canvas App, особенно когда требуется реализация сложной бизнес-логики, которая труднодостижима с помощью стандартных возможностей PowerFX. Canvas App позволяет легко интегрировать Custom API, даже без глубоких технических знаний. Это особенно ценно в сценариях, где необходимо обрабатывать данные в циклах или реализовывать рекурсию, что значительно сложнее выполнить с помощью PowerFX по сравнению с CSharp.

  2. Power Automate Flows: В Power Automate Flows Custom API может быть использован для решения задач, которые требуют написания кода, например, при выполнении операций типа switch или обработке текста. Custom API позволяет легко интегрировать код CSharp в Flows, обеспечивая более гибкую и мощную обработку данных.

  3. JavaScript в CRM: В контексте CRM, Custom API используется в JavaScript на формах entity таблиц. Это позволяет упростить вызовы и обработку данных, аналогично вызову Custom Action в CRM.

  4. Интеграция с внешними системами: Custom API обладает большой гибкостью для интеграции с различными внешними системами. Важное отличие при вызове API из внешних систем по сравнению с Canvas App, Power Automate или JavaScript – необходимость авторизации. Для этого обычно используется токен, генерируемый с использованием Client ID и Client Secret. Это позволяет безопасно взаимодействовать с системой CRM из внешних приложений, таких как Postman, обеспечивая безопасный и контролируемый доступ к функционалу CRM.


Как использовать Custom API для улучшения и интеграции функционала Dynamics CRM? Этот доступный инструмент делает процесс разработки более гибким и эффективным, предоставляя ценные возможности для расширения возможностей системы.


Как можно вызвать Custom API в Canvas App?

Для вызова Custom API в Canvas App, в первую очередь, необходимо добавить соответствующий source environment в качестве data source. Это позволяет интегрировать API непосредственно в приложение. Далее следует использование имени end point, которое является уникальным идентификатором функции, зарегистрированной в solution. Процесс вызова включает указание имени этого end point, а также, при необходимости, имени параметров, которые должны быть переданы в API.

How can I call the Custom API in Canvas App?

Существенным преимуществом использования Custom API в Canvas App является возможность обработки сложных бизнес-логик без необходимости внедрения дополнительного кода или плагинов. Это позволяет разработчикам эффективно управлять функционалом приложения, используя возможности Custom API для реализации специфических задач и операций.

Example idea

Пример использования может выглядеть следующим образом: после добавления source environment в качестве data source в Canvas App, разработчик указывает точку (.) и имя зарегистрированного в solution end point. Если в процессе вызова требуется передача параметров, они также указываются в коде вызова. После этого можно обрабатывать response, который возвращается API. Это обеспечивает гибкость и мощность при работе с пользовательскими интерфейсами и бизнес-логикой в Canvas App, делая процесс более эффективным и удобным для разработчиков.


Как можно вызвать Custom API в JavaScript?

Вызов Custom API в JavaScript осуществляется аналогично вызову Custom Actions. Используется стандартная процедура через WebAPI.online.execute(request). В этом контексте request является специально созданным объектом запроса, который включает в себя имя действия (action name) и необходимые параметры.


How can I call the Custom API in JavaScript?

Процесс создания объекта request начинается с определения имени Custom API, который нужно вызвать, и соответствующих параметров. Эти параметры могут варьироваться в зависимости от конкретного API и его требований. Например, если API требует передачи определенных данных или параметров, эти значения должны быть включены в объект request.


После создания объекта request, он передается в метод WebAPI.online.execute, который отвечает за отправку запроса к CRM и обработку ответа. Этот метод асинхронный, что позволяет разработчикам обрабатывать ответы API без блокировки пользовательского интерфейса.

How to improve interactivity in CRM?

Как улучшить интерактивность в CRM? Использовать Custom API в JavaScript на формах сущностей является ключевым подходом. Это позволяет разработчикам построить более интуитивно понятный и эффективный пользовательский интерфейс, обеспечивая глубокую интеграцию и удобное взаимодействие с пользователями. Такой метод особенно ценный для создания динамических форм, которые могут реагировать на ввод данных пользователя, делая процесс работы с системой более доступным и удобным.


Как можно вызвать Custom API в Power Automate (Flows)?

В Power Automate, использование Custom API включает несколько ключевых шагов, которые обеспечивают гладкую интеграцию и эффективную обработку данных. На примере недавнего проекта, можно рассмотреть типичный процесс использования Custom API в рамках Flows.


How can I call the Custom API in Power Automate (Flows)?
  1. Выбор источника данных: В Power Automate, начните с выбора Dataverse как источника данных. Это предоставляет доступ к различным действиям (actions), которые можно выполнять внутри Flow.

  2. Определение типа действия: В Dataverse есть два основных типа действий - outbound (исходящие) и inbound (входящие). Выбор между этими типами зависит от конкретной задачи, которую вы пытаетесь выполнить с помощью Custom API.

  3. Добавление и настройка Custom Action: Далее, добавьте нужный Custom Action, который был заранее настроен в Dataverse. При выборе действия, вам будет предоставлен список доступных параметров, которые необходимо заполнить. Эти параметры соответствуют input параметрам, заданным при создании Custom API.

  4. Работа с параметрами: После настройки и выполнения Custom Action в Flow, вы получаете доступ к output параметрам, то есть к результатам выполнения API. Это позволяет обрабатывать и использовать данные, полученные от Custom API, для дальнейших шагов в Flow.

  5. Интеграция с Power Automate: После регистрации Custom Action в Dataverse, он автоматически становится доступным в Power Automate. Это упрощает процесс интеграции, так как не требует дополнительных шагов для связывания Custom API с Flow.

improving the automation of complex business processes

Этот процесс показывает, как можно использовать Custom API в Power Automate для улучшения автоматизации сложных бизнес-процессов, обработки данных и выполнения условных операций, основанных на данных из CRM. Важно обеспечить точную настройку параметров и правильную регистрацию Custom Action для гарантии бесперебойной работы Flows.


Как можно вызвать Custom API в Postman?

В Postman процесс вызова Custom API отличается от других приложений и сервисов. В отличие от использования environment как data source в Canvas App, стандартного WebAPI.online.execute в JavaScript и стандартных outbound или inbound actions из Dataverse в Power Automate, Postman требует более сложной настройки для успешного вызова Custom API.

How can I call the Custom API in Postman?

Процесс начинается с авторизации, которая требует наличия application user. Первым шагом является генерация токена авторизации. Этот токен необходим для взаимодействия с Custom API через Postman. После получения токена, необходимо подготовить запрос, который будет включать в себя следующие ключевые компоненты:

  • CRM URL: Адрес CRM системы, в которой размещен Custom API.

  • API версия: Указание на актуальную версию API, с которой предполагается взаимодействие.

  • End point: Уникальное имя Custom API, которое было задано при его создании и регистрации в Dataverse.

Используя эти данные, можно формировать запросы различных типов (например, POST, GET, PUT) в зависимости от функционала, предоставляемого Custom API. Важно учитывать, что тип запроса должен соответствовать тому, на который зарегистрирован Custom API.

the user receives a response (output)

После отправки запроса через Postman, пользователь получает ответ (output), который может быть использован для дальнейшей работы или анализа. Этот метод позволяет тестировать и интегрировать Custom API в различные внешние системы, обеспечивая гибкость и расширяемость взаимодействия с Dynamics CRM.


Преимущества Custom API

Benefits of Custom API
  • Расширение Возможностей Dynamics CRM: Custom API значительно расширяет функциональность Dynamics CRM. Это достигается путем добавления сложных валидаций и бизнес-логики, которые ранее были недоступны. С Custom API, Dynamics CRM трансформируется, предлагая более мощные и настраиваемые возможности.

  • Универсальность Интеграции: Одно из самых замечательных преимуществ Custom API - его способность интегрироваться с различными системами. Это особенно полезно в приложениях, таких как Canvas App, JavaScript на форме CRM и Power Automate. Custom API упрощает работу с PowerFX, облегчая задачи, которые ранее требовали значительных усилий и времени.

  • Многократное Использование и Гибкость: Custom API позволяет разработчикам писать код один раз и использовать его в различных контекстах без дополнительных изменений. Например, Custom API, активирующий контакт, может быть вызван из разных мест - например, с формы в CRM или в ответ на определенное событие в Power Automate. Это устраняет необходимость в повторной разработке или дублировании кода для различных сценариев использования, упрощая процесс разработки и снижая вероятность ошибок.


Минусы Custom API

Хотя Custom API предлагает множество преимуществ, существуют определенные ограничения, которые важно учитывать при разработке:

Cons of Custom API

  • Ограничение Времени Выполнения (Timeout): Основное ограничение Custom API, как и любого другого решения, основанного на плагинах и workflows в Dynamics CRM, заключается в лимите времени выполнения операции – две минуты. Это означает, что любая операция Custom API должна завершаться в течение этого временного интервала. Если задача требует значительного времени для выполнения из-за сложной логики, больших объемов данных или сложных запросов, она может превысить данный лимит, что приведет к неполным или неверным результатам.

  • Обработка Ошибок и Ограничения на Выполнение: В случае, если выполнение Custom API превышает установленный лимит в две минуты и возникает ошибка, возможно, что выходное сообщение (output message) не будет сформировано. Это требует дополнительного планирования для обработки таких сценариев. Например, в Power Automate следует использовать настройку 'Run After' для определения действий после возникновения ошибки. Можно настроить отправку уведомления по электронной почте в случае сбоя (fail) или продолжение выполнения процесса при успешном завершении (success).

  • Проектирование и Тестирование: Учитывая эти ограничения, разработчики должны тщательно проектировать и тестировать Custom API, особенно в сценариях с потенциально длительными или сложными операциями. Необходимо заранее предусматривать механизмы обработки ошибок и оптимизировать логику для укладывания во временные рамки.


Для улучшения работы с Custom API в Dynamics CRM, важно использовать стратегическое планирование и тестирование. Это позволяет минимизировать риски, связанные с ограничениями времени выполнения и обработкой ошибок. Где можно, стоит применять доступные и удобные методы для повышения эффективности и ценности процесса.


Пример Custom API в Power Automate (Flows)

Create Sharepoint Documentation

В качестве наглядного примера использования Custom API в Power Automate (Flows) можно рассмотреть процесс создания документации SharePoint. Этот процесс демонстрирует практическую реализацию и легкость интеграции Custom API в автоматизированные рабочие процессы.

Action Name
  1. Добавление нового компонента: Процесс начинается с добавления нового компонента в Flow. Здесь выбирается действие (Action) с названием "Create Sharepoint Documentation", которое было заранее определено в рамках Custom API.

  2. Настройка Action Name: В поле имени действия (Action Name) указывается "Create Sharepoint Documentation". Это имя выбирается из предварительно созданного списка, устраняя необходимость в его дополнительном определении.

  3. Заполнение параметров: После выбора действия автоматически появляются параметры, которые необходимо заполнить. Этот шаг включает выбор определенных значений в соответствии с требованиями бизнес-логики.

  4. Обработка результата: В зависимости от типа данных, результат можно использовать напрямую без дополнительной обработки. Например, если результат является простой строкой (String), его можно выбрать и использовать без необходимости применения дополнительных формул или парсинга. Это упрощает интеграцию по сравнению с более сложными типами данных, требующими дополнительной обработки.

Power Automate

Этот пример демонстрирует, как можно удобно и эффективно использовать Custom API в Power Automate для автоматизации сложных задач, таких как построение документации SharePoint. Процесс интеграции и настройки Custom API в Flow является интуитивным и простым, делая его доступным даже для пользователей без глубоких технических знаний. Такая интеграция предоставляет гибкость и мощность в автоматизации, позволяя пользователям Dynamics CRM улучшить и оптимизировать свои рабочие процессы.


F.A.Q

Q: Есть ли гарантия, что если Custom Action выполнен успешно, то все прошло хорошо?

Is there a guarantee that if a Custom Action is executed successfully, then everything went well?

A: Да, успешное выполнение Custom Action обычно указывает на то, что все прошло хорошо. Однако, стоит учитывать сценарии, когда могут возникать ошибки на стороне Custom API. Рекомендуется использовать механизмы обработки ошибок, такие как try-catch блоки, для выявления и обработки потенциальных проблем.


Q: Как можно обрабатывать ошибки в Custom API?

A: При обнаружении ошибки в блоке catch можно записать сообщение об ошибке в output параметр. Если после выполнения блока в output параметре присутствует сообщение об ошибке, необходимо предпринять соответствующие действия. Кроме того, можно проверять наличие определенных критериев успеха, например, создания записи.


Q: Можно ли использовать Custom API для внешних систем?

A: Да, Custom API легко интегрируется с внешними системами. Однако, стоит учитывать, что различные системы могут иметь свои ограничения по авторизации и лицензированию.


Q: Are there any restrictions on the number of API calls?

Q: Есть ли ограничения по количеству вызовов API?

A: Для application user ограничения по количеству операций устанавливаются на уровне tenant или environment. По умолчанию, предоставляется 500 000 операций, с добавлением 5000 за каждого лицензионного пользователя. Ограничения распространяются на все операции, которые выполняет application user, включая создание записей.


How to handle situations when the Custom API does not fit within the timeout limit

Q: Как обрабатывать ситуации, когда Custom API не укладывается в ограничение по времени (timeout)?

A: В случае превышения временного ограничения, рекомендуется использовать стратегии, такие как Run...After в Flow, для обработки потенциальных ошибок. Можно настроить отправку уведомлений при сбое или переход к другим действиям в случае успеха.


Заключение

Custom API в Dataverse от Microsoft представляет собой доступный и удобный инструмент, который можно использовать для расширения возможностей Dynamics CRM за пределы традиционного использования. Его ценность заключается в способности адаптировать и интегрировать сложные бизнес-логики непосредственно в CRM, обеспечивая тем самым улучшение рабочих процессов. Использование Custom API позволяет автоматизировать задачи и улучшать взаимодействие с клиентами, что особенно важно в современной деловой среде.

This requires careful planning and testing

Однако важно помнить о некоторых ограничениях, включая ограничение времени выполнения операций. Это требует тщательного планирования и тестирования, чтобы гарантировать, что бизнес-логика будет выполнена эффективно и без сбоев. Разработчикам следует учитывать эти ограничения при проектировании и реализации Custom API, особенно в сценариях с высокой нагрузкой или сложными запросами данных.

Microsoft's Dataverse Custom API offers significant benefits for organizations looking to streamline and automate their business processes

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


В заключение, Custom API в Dataverse от Microsoft предлагает значительные преимущества для организаций, стремящихся к оптимизации и автоматизации своих бизнес-процессов. Он обеспечивает гибкость, масштабируемость и мощные возможности интеграции, которые могут значительно улучшить эффективность работы с CRM. При этом, эффективное использование Custom API требует понимания его возможностей и ограничений, а также внимательного планирования и тестирования для достижения наилучших результатов.


Рекомендации

  • Планирование и Проектирование: Перед началом разработки Custom API тщательно спланируйте его функциональность и интерфейс. Удостоверьтесь, что API соответствует вашим бизнес-целям и техническим требованиям.

  • Учет Ограничений по Времени: Учитывайте ограничение времени выполнения в две минуты для Custom API. Разрабатывайте эффективные и оптимизированные алгоритмы для избежания таймаутов, особенно в операциях с большим объемом данных.

  • Тестирование и Отладка: Тщательно тестируйте Custom API в различных сценариях использования. Проверьте работоспособность во всех интегрированных системах, включая Canvas App, JavaScript, Power Automate и Postman.

  • Документация и Поддержка: Обеспечьте полную и понятную документацию для вашего Custom API. Это облегчит его интеграцию и использование другими разработчиками или конечными пользователями.

  • Безопасность и Управление Доступом: Внедрите надежные механизмы безопасности и управления доступом. Убедитесь, что только авторизованные пользователи имеют доступ к вашему API.

  • Мониторинг и Обслуживание: Регулярно мониторьте использование и производительность вашего Custom API. Будьте готовы к быстрому реагированию на возможные проблемы или изменения в требованиях.

  • Обучение и Разработка Навыков: Поощряйте команду к обучению и развитию навыков работы с Custom API и связанными технологиями. Это повысит качество разработки и интеграции.

  • Интеграция с Существующими Системами: Используйте преимущества Custom API для улучшения интеграции между Dynamics CRM и другими системами, что повысит общую эффективность бизнес-процессов.

  • Управление Изменениями: При внедрении изменений в Custom API следите за их совместимостью со старыми версиями и информируйте пользователей обо всех обновлениях.

  • Обратная Связь и Итеративное Улучшение: Собирайте обратную связь от пользователей и регулярно обновляйте ваш Custom API, улучшая его функциональность и удобство использования.


9 views0 comments

Comments


bottom of page