تسجيل تطبيق العميل المخصص ل Agent 365 CLI

Important

يجب أن تكون جزءا من برنامج معاينة الحدود للحصول على وصول مبكر إلى Microsoft Agent 365. Frontier تربطك مباشرة بأحدث ابتكارات الذكاء الاصطناعي من Microsoft. تخضع المعاينات الحدودية لشروط المعاينة الحالية لاتفاقيات العملاء. نظرًا لأن هذه الميزات لا تزال قيد التطوير، فقد يتغير توفرها وقدراتها بمرور الوقت.

يتطلب CLI الوكيل 365 تسجيل تطبيق عميل مخصص في مستأجر Microsoft Entra ID الخاص بك للمصادقة وإدارة مخططات هوية الوكيل.

المتطلبات الأساسية

لتسجيل التطبيق (الخطوات 1-3):

• بشكل افتراضي، يمكن لأي مستخدم في المستأجر تسجيل التطبيقات في مركز إدارة Microsoft Entra الخاص ب Entra. ومع ذلك، يمكن لمسؤولي المستأجرين تقييد هذه القدرة.

لإضافة الأذونات ومنح الموافقة (الخطوة 4):

• أحد هذه الأدوار الإدارية مطلوب:

  • مسؤول التطبيق: موصى به - يمكنه إدارة تسجيلات التطبيقات ومنح الموافقة
  • مسؤول تطبيقات السحابة: يمكنه إدارة تسجيلات التطبيقات ومنح الموافقة
  • المسؤول العام: لديه جميع الأصوات، لكنه غير مطلوب

Tip

لا تملك صلاحية المسؤول؟ يمكنك إكمال الخطوات 1-3 بنفسك، ثم تطلب من مدير المستأجر إكمال الخطوة 4. زودهم بمعرف التطبيق (العميل) من الخطوة 3 ورابطا لقسم إعدادات صلاحيات واجهة برمجة التطبيقات (API).

الخطوة 1: تسجيل الطلب

تلخص هذه التعليمات التعليمات الكاملة لإنشاء تسجيل التطبيق.

1. اذهب إلى مركز إدارة Microsoft Entra

2. اختيار تسجيلات التطبيقات

3. حدد تسجيل جديد

4. دخل:

   • الاسم: Agent365 CLI (أو اسمك المفضل)
   • أنواع الحسابات المدعومة: الحسابات في هذا الدليل التنظيمي فقط (مستأجر واحد)
   • إعادة توجيه URI: اختر العميل العام/الأصلي (الجوال وسطح المكتب) وأدخل http://localhost:8400/

5. اختر التسجيل

الخطوة 2: تعيين رابط إعادة التوجيه

1. اذهب إلى النظرة العامة وانسخ قيمة معرف التطبيق (العميل).
2. اذهب إلى المصادقة (المعاينة) واختر إضافة رابط رابط إعادة التوجيه.
3. اختر تطبيقات الجوال وسطح المكتب وقم بتعيين القيمة إلى ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}، حيث {client-id} هي قيمة التطبيق (معرف العميل) التي تم نسخها سابقا.
4. اختر التكوين لإضافة القيمة.

الخطوة 3: نسخ معرف التطبيق (العميل)

من صفحة النظرة العامة للتطبيق، انسخ معرف التطبيق (العميل) (بصيغة GUID). أدخل هذه القيمة عند استخدام a365 config init الأمر.

Tip

لا تخلط بين هذه القيمة ومعرف الكائن - تحتاج إلى معرف التطبيق (العميل).

الخطوة 4: تكوين صلاحيات API

Important

امتيازات المسؤول مطلوبة لهذه الخطوة. إذا كنت مطورا بدون وصول للمسؤول، أرسل معرف التطبيق (العميل) من الخطوة 3 إلى مسؤول المستأجر الخاص بك واطلب منهم إكمال هذه الخطوة.

Note

اعتبارا من ديسمبر 2025، كانت الأذونتان AgentIdentityBlueprint.* واجهات برمجة تطبيقات تجريبية وقد لا تكونان مرئيتين في مركز إدارة Microsoft Entra. إذا أصبحت هذه الأصار متاحة بشكل عام في مستأجرك، يمكنك استخدام الخيار أ لجميع الأذونات.

اختر الطريقة المناسبة:

• الخيار الأول: استخدام مركز إدارة Microsoft Entra لجميع الأذونات (إذا كانت صلاحيات النسخة التجريبية مرئية)
• الخيار ب: استخدام واجهة برمجة تطبيقات Microsoft Graph لإضافة جميع الأذونات (ينصح به إذا لم تكن صلاحيات البيتا مرئية)

الخيار أ: مركز إدارة Microsoft Entra (الطريقة القياسية)

استخدم هذه الطريقة إذا كانت صلاحيات البيتا واضحة في المستأجر الخاص بك.

1. في تسجيل التطبيق، اذهب إلى صلاحيات API

2. اختر إضافة إذن → Microsoft Graph → الأذونات المفوضة

   Important

   يجب عليك استخدام الأذونات المفوضة (وليس صلاحيات التطبيق). يقوم مؤشر التحكم بالتحقق بشكل تفاعلي - تقوم بتسجيل الدخول، ويعمل نيابة عنك. انظر نوع الإذن الخطأ إذا أضفت أذونات التطبيق عن طريق الخطأ.

3. أضف هذه الأذونات الخمسة واحدة تلو الأخرى:

   الإذن	الغرض
   AgentIdentityBlueprint.ReadWrite.All	إدارة إعدادات مخطط الوكيل (واجهة برمجة التطبيقات التجريبية)
   AgentIdentityBlueprint.UpdateAuthProperties.All	تحديث أجنحة Agent Blueprint القابلة للوراثة (واجهة برمجة التطبيقات التجريبية)
   Application.ReadWrite.All	إنشاء وإدارة التطبيقات ومخططات الوكلاء
   DelegatedPermissionGrant.ReadWrite.All	منح صلاحيات لمخططات الوكيل
   Directory.Read.All	اقرأ بيانات الدليل للتحقق من الصحة

   لكل إذن:

   • في مربع البحث، اكتب اسم الإذن (على سبيل المثال، AgentIdentityBlueprint.ReadWrite.All)
   • ضع علامة على مربع الاختيار بجانب الإذن
   • حدد إضافة أذونات
   • كرر ذلك لجميع الأذونات الخمسة

4. اختر منح موافقة الإدارة ل [مستأجرك]

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

5. تحقق من جميع الأصوات تظهر علامات تحقق خضراء تحت الحالة

إذا لم تكن صلاحيات البيتا (AgentIdentityBlueprint.*) مرئية، انتقل إلى الخيار ب.

الخيار ب: واجهة برمجة تطبيقات Microsoft Graph (لأذونات النسخة التجريبية)

استخدم هذه الطريقة إذا AgentIdentityBlueprint.* لم تكن الأذونات مرئية في مركز إدارة Microsoft Entra.

تحذير

إذا استخدمت هذه الطريقة في واجهة برمجة التطبيقات، فلا تستخدم زر "منح موافقة المسؤول" في مركز إدارة Microsoft Entra بعد ذلك. طريقة API تمنح موافقة المسؤول تلقائيا، وباستخدام زر مركز إدارة Microsoft Entra يحذف صلاحيات البيتا الخاصة بك. راجع اختفاء صلاحيات النسخة التجريبية لمزيد من التفاصيل.

1. مستكشف الرسم البياني المفتوح

2. سجل الدخول بحساب المسؤول الخاص بك (مسؤول التطبيق أو مسؤول التطبيقات السحابية)

3. امنح موافقة المسؤول باستخدام واجهة برمجة تطبيقات الرسم البياني. لإكمال ذلك، تحتاج إلى:

   • معرف المدير. تحتاج إلى SP_OBJECT_ID قيمة متغيرة.
   • معرف موارد الرسم البياني. تحتاج إلى GRAPH_RESOURCE_ID قيمة متغيرة.
   • أنشئ (أو حدث) الأذونات المفوضة باستخدام نوع المورد oAuth2PermissionGrant مع SP_OBJECT_ID قيم و GRAPH_RESOURCE_ID المتغيرات.

لإكمال ذلك، استخدم المعلومات في الأقسام التالية.

احصل على معرف المديرة لخدمتك

ال "Service Principal" هو هوية تطبيقك في المستأجر، وهو أمر مطلوب قبل منح الأذونات عبر API.

1. اضبط طريقة مستكشف الرسوم البيانية على GET واستخدم هذا الرابط (استبدلها <YOUR_CLIENT_APP_ID> بمعرف العميل الفعلي الخاص بك من الخطوة 3: نسخ معرف التطبيق (العميل):

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '<YOUR_CLIENT_APP_ID>'&$select=id
   

2. حدد تشغيل الاستعلام.

   • إذا نجح الاستعلام، القيمة التي تم إرجاعها هي القيمة التي تم استعادتها هي .SP_OBJECT_ID

   • إذا فشل الاستعلام مع وجود خطأ في الأدوان، اختر تبويب تعديل الأذونات ، وافق على الأصوات المطلوبة، ثم اختر تشغيل الاستعلام مرة أخرى. القيمة المرتجعة هي القيمة التي تم استرجاعها هي .SP_OBJECT_ID

   • إذا أعاد الاستعلام نتائج فارغة ("value": [])، أنشئ مبدأ الخدمة باستخدام الخطوات التالية:

     1. قم بتعيين طريقة POST واستخدم هذا الرابط:

        https://graph.microsoft.com/v1.0/servicePrincipals
        

        جسم الطلب (استبداله YOUR_CLIENT_APP_ID بمعرف العميل الفعلي الخاص بك):

        {
           "appId": "YOUR_CLIENT_APP_ID"
        }
        

     2. حدد تشغيل الاستعلام. يجب أن تحصل على 201 Created رد. القيمة المرتجعة id هي القيمة التي تم استرجاعها هي .SP_OBJECT_ID

احصل على معرف موارد الرسم البياني الخاص بك

1. قم بتعيين طريقة مستكشف الرسوم البيانية على GET واستخدم هذا العنوان:

   https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appId eq '00000003-0000-0000-c000-000000000000'&$select=id
   

2. حدد تشغيل الاستعلام.

   • إذا نجح الاستعلام، انسخ القيمة id . هذا هو .GRAPH_RESOURCE_ID
   • إذا فشل الاستعلام مع وجود خطأ في الأدوان، اختر تبويب تعديل الأذونات ، وافق على الأصوات المطلوبة، ثم اختر تشغيل الاستعلام مرة أخرى. انسخ القيمة id . هذا هو .GRAPH_RESOURCE_ID

إنشاء الأذونات المفوضة

تمنح هذه النداء موافقة المسؤول على مستوى المستأجر لجميع الأذونات الخمسة، بما في ذلك إذنتي التجريبيين اللتين لا تظهران في مركز إدارة Microsoft Entra.

1. قم بتعيين طريقة مستكشف الرسوم البيانية على POST واستخدم هذا الرابط ونص الطلب:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants
   

   نص الطلب:

   {
   "clientId": "<SP_OBJECT_ID>",
   "consentType": "AllPrincipals",
   "principalId": null,
   "resourceId": "<GRAPH_RESOURCE_ID>",
   "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

2. حدد تشغيل الاستعلام.

   • إذا تلقيت 201 Created ردا: نجاح! scope الحقل في الرد يعرض جميع أسماء الأذونات الخمسة. انتهى أمرك.
   • إذا فشل الاستعلام مع وجود خطأ في الأمور (على الأرجح DelegatedPermissionGrant.ReadWrite.All)، اختر تبويب تعديل الأدנות، ثم الموافقة على DelegatedPermissionGrant.ReadWrite.All، ثم اختر تشغيل الاستعلام مرة أخرى.
   • إذا حصلت على خطأ Request_MultipleObjectsWithSameKeyValue: هناك منحة موجودة بالفعل. ربما أضاف أحدهم أذونات سابقا. راجع التحديث التالي لتفويض الأذونات.

تحذير

consentType: "AllPrincipals" POST الطلب يمنح بالفعل موافقة الإدارة على مستوى المستأجر. لا تقم باختيار "منح موافقة المسؤول" في مركز إدارة Microsoft Entra بعد استخدام هذه الطريقة - فهذا يحذف صلاحيات البيتا لأن مركز إدارة Microsoft Entra لا يستطيع رؤية صلاحيات البيتا ويكتب فوق موافقتك الممنوحة من API باستخدام الأذونات الظاهرة فقط.

تحديث الأذونات المفوضة

عندما تظهر Request_MultipleObjectsWithSameKeyValue لك رسالة خطأ باستخدام خطوات إنشاء الأذونات المفوضة، استخدم هذه الخطوات لتحديث الأذونات المفوضة.

1. قم بتعيين طريقة مستكشف الرسوم البيانية على GET واستخدم هذا العنوان:

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'SP_OBJECT_ID_FROM_ABOVE'
   

2. حدد تشغيل الاستعلام. انسخ القيمة id من الرد. هذا هو YOUR_GRANT_ID.

3. قم بتعيين طريقة مستكشف الرسوم البيانية على PATCH واستخدم هذا الرابط باستخدام YOUR_GRANT_ID.

   https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<YOUR_GRANT_ID>
   

   نص الطلب:

   {
      "scope": "Application.ReadWrite.All Directory.Read.All DelegatedPermissionGrant.ReadWrite.All AgentIdentityBlueprint.ReadWrite.All AgentIdentityBlueprint.UpdateAuthProperties.All"
   }
   

4. حدد تشغيل الاستعلام. يجب أن تحصل على 200 OK رد بجميع الأذونات الخمسة في scope الميدان.

استكشاف الأخطاء وإصلاحها

يحتوي هذا القسم على معلومات حول كيفية استكشاف أخطاء تسجيل تطبيقات العميل المخصص.

نوع الإذن خاطئ (تفويض مقابل تطبيق)

العرض: يفشل مؤشر التحكم في الإشارة بسبب أخطاء المصادقة أو أخطاء رفض الأذون.

السبب الجذري: أضفت أصلاحيات التطبيق بدلا من الأذونات المفوضة.

نوع الإذن	متى تستخدم	كيف يستخدمه عامل 365 CLI
مفوض ("النطاق")	يسجل المستخدم الدخول بشكل تفاعلي	العميل 365 CLI يستخدم هذا - أنت تسجل الدخول، وتعمل CLI نيابة عنك
التطبيق ("الدور")	الخدمة تعمل بدون مستخدم	لا تستخدم - فقط للخدمات الخلفية/الشياطين

لماذا تم تفويضه؟

• تقوم بتسجيل الدخول بشكل تفاعلي (مصادقة المتصفح)
• تقوم CLI بالإجراءات كما أنت (سجلات التدقيق تظهر هويتك)
• أكثر أمانا - محدودا بصلاحياتك الفعلية
• يضمن المساءلة والامتثال

الحل:

1. اذهب إلى مركز >> الخاصة بك >
2. قم بإزالة أي صلاحيات تطبيق. تظهر هذه الأذونات ك Application في عمود النوع .
3. أضف نفس الأذونات التي أضافها الأذونات المفوضة
4. امنح موافقة الإدارة مرة أخرى

تختفي صلاحيات النسخة التجريبية بعد موافقة مسؤول مركز إدارة Microsoft Entra

العرض: استخدمت الخيار ب: واجهة برمجة تطبيقات Microsoft Graph (لأذونات النسخة التجريبية) لإضافة أمنيات بيتا، لكنها اختفت بعد اختيار منح موافقة المسؤول في مركز إدارة Microsoft Entra.

السبب الجذري: مركز إدارة Microsoft Entra لا يعرض أمناء البيتا في واجهة المستخدم، لذا عند اختيار منح موافقة المسؤول، فإنه يمنح فقط الأذونات المرئية ويكتب فوق الموافقة الممنوحة من API.

لماذا يحدث هذا:

1. تستخدم واجهة برمجة تطبيقات الرسم البياني (الخيار B) لإضافة جميع الأذونات الخمسة بما في ذلك صلاحيات البيتا
2. استدعاء واجهة برمجة التطبيقات (API) consentType: "AllPrincipals"يمنح بالفعل موافقة المسؤول على مستوى المستأجر
3. تذهب إلى مركز إدارة Microsoft Entra وترى فقط ثلاث صلاحيات لأن صلاحيات البيتا غير مرئية
4. تختار منح موافقة المسؤول معتقدا أنك بحاجة لذلك
5. مركز إدارة Microsoft Entra يقوم باستبدال موافقتك الممنوحة من قبل واجهة برمجة التطبيقات باستخدام الأذونات الثلاثة الظاهرة فقط
6. تم الآن حذف صلاحيتي البيتا الخاصة بك

الحل:

• لا تستخدم أبدا موافقة مسؤول مركز إدارة Microsoft Entra بعد طريقة API: طريقة API تمنح موافقة المسؤول بالفعل
• إذا قمت بحذف صلاحيات البيتا عن طريق الخطأ، أعد تشغيل الخيار B الخطوة 3 (منح موافقة المسؤول باستخدام واجهة برمجة تطبيقات الرسم البياني) لاستعادتها. تحصل على Request_MultipleObjectsWithSameKeyValue خطأ - اتبع الخطوات لتحديث الأمنات المفوضة.
• للتحقق من إدراج جميع الأذونات الخمسة، تحقق من scope الحقل في POST استجابة OR PATCH .

أخطاء التحقق

يقوم مؤشر التحكم تلقائيا بالتحقق من تطبيق العميل عند تشغيل a365 setup أو a365 config init.

المشاكل الشائعة:

• لم يتم العثور على التطبيق: تحقق من نسخ معرف التطبيق (العميل) (وليس معرف الكائن)
• الأذونات المفقودة: أضف جميع الأذونات الخمسة المطلوبة
• موافقة المسؤول لم تمنح:
  • إذا استخدمت الخيار أ (مركز مسؤول مايكروسوفت إنترا فقط): اختر منح موافقة المسؤول في مركز إدارة مايكروسوفت إنترا
  • إذا استخدمت الخيار B (واجهة برمجة تطبيقات الرسم البياني): أعد تشغيل POST طلب or PATCH . لا تستخدم زر موافقة مركز إدارة Microsoft Entra
• نوع الإذن خاطئ: استخدم الأذونات المفوضة، وليس صلاحيات التطبيق

للحصول على تفاصيل استكشاف الأخطاء، راجع تسجيل تطبيق في Microsoft Entra ID.

أفضل الممارسات الأمنية

من المستحسن القيام بما يلي:

• استخدم تسجيل المستأجر الواحد
• امنح فقط التصاريح الخمسة المطلوبة المفوضة
• أذونات التدقيق بانتظام
• قم بإزالة التطبيق عندما لا تعود الحاجة

لا:

• تصاريح منح طلب التقديم (الاستخدام المفوض فقط)
• شارك معرف العميل علنا
• منح أصار أخرى غير ضرورية
• استخدم التطبيق لأغراض أخرى

الخطوات التالية

الآن بعد أن تم تسجيل تطبيق العميل المخصص الخاص بك، يمكنك استخدامه مع واجهة الوكيل 365 في دورة حياة تطوير الوكيل 365: دورة حياة تطوير الوكيل 365