Поделиться через

Работа с 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-интерфейс с ключом подписки.

  1. Войдите в Customer Insights - Data или зарегистрируйтесь на пробную версию Customer Insights.

  2. Перейдите в раздел Параметры>Разрешения и выберите вкладку API-интерфейсы.

  3. Если API-доступ к среде не настроен, выберите Включить.

    Включение API-интерфейсов создает первичный и вторичный ключ подписки для вашей среды, который используется в запросах API. Чтобы создать ключи, выберите Повторно создать первичный или Повторно создать вторичный на вкладке API-интерфейсы.

  4. Выберите Ознакомьтесь с нашими API-интерфейсами, чтобы попробовать API-интерфейсы.

  5. Найдите и выберите операцию API-интерфейса и выберите Попробовать.

    Как протестировать API.

  6. На боковой панели установите значение в раскрывающемся меню Авторизация как неявная. Заголовок Authorization добавляется с токеном носителя. Ваш ключ подписки заполняется автоматически.

  7. При желании добавьте все необходимые параметры запроса.

  8. Прокрутите до нижней части боковой панели и выберите Отправить.

    Ответ HTTP отображается в нижней части области.

Создание регистрации нового приложения на портале Azure

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

  1. Заполните раздел начала работы.

  2. Войдите на портал Azure с учетной записью, у которой есть доступ к данным Customer Insights.

  3. Выполните поиск, затем выберите Регистрации приложений.

  4. Выберите Новая регистрация и укажите имя приложения, выберите тип учетной записи.

    Также можно добавить URL-адрес перенаправления. Адреса http://localhost будет достаточно для разработки приложения на вашем локальном компьютере.

  5. Выберите Зарегистрировать.

  6. При регистрации нового приложения перейдите к Разрешения API.

  7. Выберите пункт Добавить разрешение, а затем — Dynamics 365 AI для Customer Insights в боковой области.

  8. Для Тип разрешения выберите Делегированные разрешения, а затем выберите разрешение user_impersonation.

  9. Выберите Добавить разрешения.

  10. Выберите Предоставить согласие администратора для…, чтобы завершить регистрацию приложения.

  11. Для доступа к API без входа пользователя в систему просмотрите раздел Задание разрешений приложения "сервер-сервер".

Вы можете использовать идентификатор приложения/клиента для регистрации этого приложения в библиотеке проверки подлинности Microsoft (MSAL), чтобы получить токен носителя для отправки с вашим запросом в API.

Для получения информации об использовании API в наших клиентских библиотеках см. Клиентские библиотеки Customer Insights.

Задание разрешений приложения "сервер-сервер"

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

  1. При регистрации приложения на портале Azure перейдите в Разрешения API.

  2. Выберите Добавить разрешение.

  3. Выберите вкладку API-интерфейсы, которые использует моя организация и выберите Dynamics 365 AI для Customer Insights из списка.

  4. Для поля Тип разрешения выберите Разрешения приложения, а затем выберите разрешение api.access.

  5. Выберите Добавить разрешения.

  6. При регистрации нового приложения вернитесь в Разрешения API.

  7. Выберите Предоставить согласие администратора для…, чтобы завершить регистрацию приложения.

  8. Добавьте имя регистрации приложения в качестве пользователя в Customer Insights - Data.

    1. Откройте Customer Insights - Data, перейдите в раздел Параметры>Разрешения и выберите Добавить пользователей.

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

Примеры запросов

Краткий список примеров запросов 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#

  1. В Visual Studio откройте NuGet Package Manager (Диспетчер пакетов) для вашего проекта.

  2. Найдите Microsoft.Dynamics.CustomerInsights.Api.

  3. Выберите Установить, чтобы добавить пакет в проект.

    Также можно запустить эту команду в консоли диспетчера пакетов NuGet: Install-Package -Id Microsoft.Dynamics.CustomerInsights.Api -Source nuget.org -ProjectName <project name> [-Version <version>]

Использование клиентской библиотеки C#

  1. Используйте библиотеку проверки подлинности Microsoft (MSAL), чтобы получить AccessToken, используя вашу существующую регистрацию приложения Azure.

  2. После успешной аутентификации и получения токена создайте новый или используйте существующий клиент HttpClient с параметром DefaultRequestHeaders "Авторизация", для которого установлено значение Носитель "маркер доступа", и параметром Ocp-Apim-Subscription-Key, для которого установлено значение ключ подписки из вашей среды Customer Insights - Data.

    Сбросьте заголовок Авторизация, когда это необходимо. Например, когда срок действия токена истек.

  3. Передайте этот HttpClient в создание клиента CustomerInsights.

  4. Совершайте вызовы с клиентом в "методы расширения", например, GetAllInstancesAsync. Если доступ к базовому Microsoft.Rest.HttpOperationResponse является предпочтительным, используйте "методы сообщений http", например GetAllInstancesWithHttpMessagesAsync.

  5. Ответ, скорее всего, будет типа object, потому что метод может возвращать несколько типов (например, IList<InstanceInfo> и ApiErrorResult). Чтобы проверить тип возврата, используйте объекты в типах ответов, указанных на странице сведений об API для этой операции.

    Если требуется дополнительная информация по запросу, используйте методы сообщений http для доступа к необработанному объекту ответа.

Пакет NodeJS

Используйте клиентские библиотеки NodeJS, доступные через NPM: https://www.npmjs.com/package/@microsoft/customerinsights

Пакет Python

Используйте клиентские библиотеки Python, доступные через PyPi: https://pypi.org/project/customerinsights/