Работа с API Customer Insights - Data
Dynamics 365 Customer Insights - Data предоставляет API-интерфейсы для создания ваших собственных приложений на основе ваших данных в Customer Insights. Подробная информация об этих API-интерфейсах приведена в разделе Справочник по API-интерфейсу. Они включают дополнительную информацию об операциях, параметрах и ответах.
Заметка
Доступ к таблицам Customer Insights - Data также можно получить с помощью API Dataverse. Мы рекомендуем использовать API Dataverse для запроса данных Customer Insights, поскольку они предлагают более обширную фильтрацию, большую пропускную способность и меньшую задержку. Дополнительную информацию см. в разделе API-интерфейсы Dataverse для Customer Insights.
Начинайте пробовать API-интерфейсы
Администратор должен включить доступ API к вашим данным. После включения доступа любой пользователь может использовать API-интерфейс с ключом подписки.
Войдите в Customer Insights - Data или зарегистрируйтесь на пробную версию Customer Insights.
Перейдите в раздел Параметры>Разрешения и выберите вкладку API-интерфейсы.
Если API-доступ к среде не настроен, выберите Включить.
Включение API-интерфейсов создает первичный и вторичный ключ подписки для вашей среды, который используется в запросах API. Чтобы создать ключи, выберите Повторно создать первичный или Повторно создать вторичный на вкладке API-интерфейсы.
Выберите Ознакомьтесь с нашими API-интерфейсами, чтобы попробовать API-интерфейсы.
Найдите и выберите операцию API-интерфейса и выберите Попробовать.
На боковой панели установите значение в раскрывающемся меню Авторизация как неявная. Заголовок
Authorization
добавляется с токеном носителя. Ваш ключ подписки заполняется автоматически.При желании добавьте все необходимые параметры запроса.
Прокрутите до нижней части боковой панели и выберите Отправить.
Ответ HTTP отображается в нижней части области.
Создание регистрации нового приложения на портале Azure
Создайте новую регистрацию приложения, чтобы использовать API-интерфейсы в приложении Azure с использованием делегированных разрешений.
Заполните раздел начала работы.
Войдите на портал Azure с учетной записью, у которой есть доступ к данным Customer Insights.
Выполните поиск, затем выберите Регистрации приложений.
Выберите Новая регистрация и укажите имя приложения, выберите тип учетной записи.
Также можно добавить URL-адрес перенаправления. Адреса http://localhost будет достаточно для разработки приложения на вашем локальном компьютере.
Выберите Зарегистрировать.
При регистрации нового приложения перейдите к Разрешения API.
Выберите пункт Добавить разрешение, а затем — Dynamics 365 AI для Customer Insights в боковой области.
Для Тип разрешения выберите Делегированные разрешения, а затем выберите разрешение user_impersonation.
Выберите Добавить разрешения.
Выберите Предоставить согласие администратора для…, чтобы завершить регистрацию приложения.
Для доступа к API без входа пользователя в систему просмотрите раздел Задание разрешений приложения "сервер-сервер".
Вы можете использовать идентификатор приложения/клиента для регистрации этого приложения в библиотеке проверки подлинности Microsoft (MSAL), чтобы получить токен носителя для отправки с вашим запросом в API.
Для получения информации об использовании API в наших клиентских библиотеках см. Клиентские библиотеки Customer Insights.
Задание разрешений приложения "сервер-сервер"
Создайте регистрацию приложения, которая не требует взаимодействия с пользователем и может выполняться на сервере.
При регистрации приложения на портале Azure перейдите в Разрешения API.
Выберите Добавить разрешение.
Выберите вкладку API-интерфейсы, которые использует моя организация и выберите Dynamics 365 AI для Customer Insights из списка.
Для поля Тип разрешения выберите Разрешения приложения, а затем выберите разрешение api.access.
Выберите Добавить разрешения.
При регистрации нового приложения вернитесь в Разрешения API.
Выберите Предоставить согласие администратора для…, чтобы завершить регистрацию приложения.
Добавьте имя регистрации приложения в качестве пользователя в Customer Insights - Data.
Откройте Customer Insights - Data, перейдите в раздел Параметры>Разрешения и выберите Добавить пользователей.
Найдите имя регистрации вашего приложения, выберите его в результатах поиска и выберите Сохранить.
Примеры запросов
Краткий список примеров запросов OData для работы с API-интерфейсами см. в разделе Примеры запросов OData.
Клиентские библиотеки Customer Insights
Начните использовать клиентские библиотеки, доступные для API-интерфейсов Customer Insights - Data. Весь исходный код библиотеки и примеры приложений можно найти в репозитории GitHub.
C# NuGet
Используйте клиентские библиотеки C# с NuGet.org. В настоящее время этот пакет предназначен для платформ netstandard2.0 и netcoreapp2.0. Для получения дополнительной информации о пакете NuGet, см. раздел Microsoft.Dynamics.CustomerInsights.Api.
Добавление клиентской библиотеки C# в проект C#
В Visual Studio откройте NuGet Package Manager (Диспетчер пакетов) для вашего проекта.
Найдите Microsoft.Dynamics.CustomerInsights.Api.
Выберите Установить, чтобы добавить пакет в проект.
Также можно запустить эту команду в консоли диспетчера пакетов NuGet:
Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]
Использование клиентской библиотеки C#
Используйте библиотеку проверки подлинности Microsoft (MSAL), чтобы получить
AccessToken
, используя вашу существующую регистрацию приложения Azure.После успешной аутентификации и получения токена создайте новый или используйте существующий клиент
HttpClient
с параметром DefaultRequestHeaders "Авторизация", для которого установлено значение Носитель "маркер доступа", и параметром Ocp-Apim-Subscription-Key, для которого установлено значение ключ подписки из вашей среды Customer Insights - Data.Сбросьте заголовок Авторизация, когда это необходимо. Например, когда срок действия токена истек.
Передайте этот
HttpClient
в создание клиентаCustomerInsights
.Совершайте вызовы с клиентом в "методы расширения", например,
GetAllInstancesAsync
. Если доступ к базовомуMicrosoft.Rest.HttpOperationResponse
является предпочтительным, используйте "методы сообщений http", напримерGetAllInstancesWithHttpMessagesAsync
.Ответ, скорее всего, будет типа
object
, потому что метод может возвращать несколько типов (например,IList<InstanceInfo>
иApiErrorResult
). Чтобы проверить тип возврата, используйте объекты в типах ответов, указанных на странице сведений об API для этой операции.Если требуется дополнительная информация по запросу, используйте методы сообщений http для доступа к необработанному объекту ответа.
Пакет NodeJS
Используйте клиентские библиотеки NodeJS, доступные через NPM: https://www.npmjs.com/package/@microsoft/customerinsights
Пакет Python
Используйте клиентские библиотеки Python, доступные через PyPi: https://pypi.org/project/customerinsights/