التعامل مع واجهات API في Customer Insights - Data

يوفر Dynamics 365 Customer Insights - Data واجهات برمجة تطبيقات لبناء التطبيقات الخاصة بك استنادا إلى بياناتك في Customer Insights. يمكن العثور على تفاصيل واجهات API هذه في مرجع واجهات API‏‎. وهي تتضمن معلومات إضافية حول العمليات والمعلمات والاستجابات.

بدء تجربة واجهة API

يجب على المسؤول تمكين وصول API إلى بياناتك. وبمجرد تمكين الوصول، يمكن لأي مستخدم استخدام API باستخدام مفتاح الاشتراك.

1. سجل دخولك إلى Customer Insights - Data أو للحصول على إصدار تجريبي من Customer Insights.

2. انتقل إلى الإعدادات>الأذونات وحدد علامة التبويب APIs.

3. إذا لم يتم إعداد وصول API إلى البيئة، حدد تمكين.

   يؤدي تمكين واجهات API إلى إنشاء مفتاح اشتراك أساسي وثانوي لبيئتك يتم استخدامه في طلبات API. لإعادة إنشاء المفاتيح، حدد إعادة إنشاء المفتاح الأساسي أو إعادة إنشاء المفتاح الثانوي في علامة التبويب واجهات برمجة التطبيقات.

4. حدد استكشاف واجهات API الخاصة بنا لتجربة واجهات API.

5. ابحث عن عملية 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 for Customer Insights في الجزء الجانبي.

8. بالنسبة إلى نوع الإذن، حدد الأذونات المفوضة، ثم حدد إذن انتحال شخصية المستخدم.

9. حدد إضافة أذونات.

10. حدد منح موافقة المسؤول ل... لإكمال تسجيل التطبيق.

11. للوصول إلى واجهة برمجة التطبيقات دون تسجيل دخول المستخدم ، انتقل إلى تعيين أذونات التطبيق من خادم إلى خادم.

يمكنك استخدام معرف التطبيق/العميل لتسجيل هذا التطبيق باستخدام مكتبة المصادقة من Microsoft (MSAL) للحصول علي رمز مميز حامل لإرساله مع طلبك إلى API.

للحصول على معلومات حول استخدام واجهات برمجة التطبيقات في مكتبات عملائنا، راجع مكتبات عميل Customer Insights.

تعيين أذونات التطبيق من خادم إلى خادم

يمكنك إنشاء تسجيل تطبيق لا يحتاج إلى تفاعل المستخدم ويمكن تشغيله على خادم.

1. في تسجيل التطبيق في مدخل Azure، انتقل إلى أذونات واجهة API.

2. حدد إضافة إذن.

3. حدد واجهات برمجة التطبيقات (APIS) التي تستخدمها مؤسستيواختر الذكاء الاصطناعي في Dynamics 365 لـ Customer Insights من القائمة.

4. بالنسبة إلى نوع الإذن، حدد أذونات التطبيقات ، ثم حدد إذن CustomerInsights.Api.All.

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 and netcoreapp2.0. لمزيد من المعلومات حول الحزمة NuGet، راجع Microsoft.Dynamics.CustomerInsights.Api.

إضافة مكتبة العملاء C# إلى مشروع C#‎

1. في Visual Studio، افتح NuGet Package Manager لمشروعك.

2. ابحث عن Microsoft.Dynamics.CustomerInsights.Api.

3. حدد تثبيت لإضافة الحزمة إلى المشروع.

   أو بدلاً من ذلك، يمكنك تشغيل هذا الأمر في NuGet Package Manager Console: 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/