تكوين واجهة سطر الأوامر لـ Agent 365 لسُحُب الحكومة الأمريكية

بشكل افتراضي، يستهدف Agent 365 CLI سحابة Microsoft التجارية. يقوم بالمصادقة باستخدام https://login.microsoftonline.com، ويستدعي Microsoft Graph عند https://graph.microsoft.com، ويستدعي خدمات Agent 365 عند https://agent365.svc.cloud.microsoft. سحابات Microsoft 365 التابعة لحكومة الولايات المتحدة هي السحابة المجتمعية الحكومية (GCC)، وGCC High، وسحابة وزارة الدفاع (DoD). لاستخدام واجهة سطر الأوامر (CLI) في إحدى هذه السحابات، اختر بيئة السحابة وقم بتكوين نقاط النهاية لتلك السحابة.

تشرح هذه المقالة كيفية تعامل واجهة سطر الأوامر مع إعدادات السحابة وكيفية تكوينها في ملفك a365.config.json أو باستخدام متغيرات البيئة.

Note

تتوفر ميزة تحديد نقاط النهاية المراعي للسحابة في الإصدارات الحديثة من CLI Agent 365. قم بالتحديث إلى أحدث إصدار قبل أن تقوم بتكوين سحابة حكومية أمريكية. للحصول على تعليمات التحديث، راجع تحديث CLI الخاص بالعامل 365.

مهم

نقاط النهاية القابلة للتكوين لا تضمن توفر كل خدمة أو ميزة من Agent 365 في كل سحابة. بعض الخدمات والميزات المتوفرة في السحابة التجارية قد لا تكون متاحة بعد في GCC أو GCC High أو DoD. تأكد من توفر الخدمة لسحابتك قبل تشغيل الإعداد. للحصول على توفر ميزة Agent 365 في GCC، راجع وصف خدمة Microsoft Agent 365.

البيئات السحابية المدعومة

اسم البيئة يُخبر CLI بأي سحابة تستهدفها. ضبطها بشكل صريح لكل سحابة حكومية أمريكية.

السحابة	`environment` قيمة	لاحقة متغير البيئة (`<ENV>`)
تجاري (افتراضي)	`prod`	`PROD`
مجلس التعاون الخليجي	`gcc`	`GCC`
GCC High	`gcc-high`	`GCC_HIGH`
وزاره الدفاع	`dod`	`DOD`

يتحكم اسم البيئة في سلوكين:

يقرأ CLI المتغيرات ذات النطاق الخاص بالبيئة والتي تطابق اسم البيئة. على سبيل المثال، مع gcc-high، تقرأ واجهة سطر الأوامر A365_GRAPH_BASE_URL_GCC_HIGH.
يمنح الإعداد صلاحيات على مورد Agent 365 Observability للسحابة المختارة. لمزيد مِن المعلومات، راجع أذونات إمكانية المراقبة.

اسم البيئة لا يغير مضيف السلطة أو عنوان الرابط الأساسي Microsoft Graph أو نقاط نهاية خدمة Agent 365 بمفرده. قم بتكوين تلك النقاط النهائية لسحابتك كما هو موضح في تكوين GCC وتكوين GCC High أو DoD.

مهم

لا تستخدم اسم سحابة Azure CLI AzureUSGovernment كبيئة. هذا الاسم لا يميز بين GCC وGCC High وDoD، لذا يبلغ CLI عن خطأ في التكوين عندما يحتاج إلى إعدادات خاصة بالسحابة. استخدم gcc، gcc-high، أو dod بدلا من ذلك.

كيف يحدد CLI إعدادات السحابة

يقوم CLI بحل اسم البيئة أولا، ثم يستخدمه لحل كل نقطة نهاية.

اسم البيئة

يستخدم CLI أول قيمة يجدها:

الحقل environment في a365.config.json.
متغير بيئة A365_ENVIRONMENT.
بالنسبة لأوامر الإعداد التي تعمل بدون ملف a365.config.json، اسم سحابة Azure CLI النشطة هو (az cloud show). إذا كانت سحابة Azure CLI هي AzureUSGovernment، يتوقف الإعداد ويطلب منك تعيين A365_ENVIRONMENT إلى gcc أو gcc-high أو dod.
الخيار الافتراضي، prod.

عندما يُنشئ الإعداد ملف a365.config.json، يسجل القيم المحلولة environment، authorityHost، وgraphBaseUrl بحيث تستهدف الأوامر اللاحقة السحابة نفسها.

develop list-available الأمر لا يقرأ a365.config.json. دائما يقرأ البيئة من A365_ENVIRONMENT، لذا قم بتعيين هذا المتغير عند استخدام الأمر في سحابة حكومة الولايات المتحدة.

مضيف التخويل وعنوان URL الأساسي لـ Microsoft Graph

لكل نقطة نهاية، تستخدم واجهة سطر الأوامر أول قيمة تجدها:

المتغير البيئي المحدود بالبيئة (A365_AUTHORITY_HOST_<ENV> أو A365_GRAPH_BASE_URL_<ENV>).
حقل المطابقة في a365.config.json (authorityHost أو graphBaseUrl).
الإعداد الافتراضي للسحابة التجارية (https://login.microsoftonline.com أو https://graph.microsoft.com).

لا يقرأ CLI هذه الإعدادات من المتغيرات غير المُلحقة بلاحقة مثل A365_GRAPH_BASE_URL.

يجب أن تكون كل قيمة تم تحليلها عبارة عن أصل يستخدم HTTPS: مخطط ومضيف ومنفذ اختياري فقط. لا تدرج مسارًا أو معلمات الاستعلام أو المقطع أو معلومات المستخدم. على سبيل المثال، تقبل واجهة سطر الأوامر https://login.microsoftonline.us لكنها ترفض https://login.microsoftonline.us/common. إذا فشلت قيمة في التحقق من الصحة، تتوقف واجهة سطر الأوامر مع ظهور خطأ.

تطبّق واجهة سطر الأوامر مضيف جهة المصادقة وعنوان URL الأساسي لـ Graph اللذين تم تحديدهما بشكل متسق فِي تدفقات الإعداد، والموافقة، والمصادقة، والاستعلام عن Microsoft Entra ID، والتنظيف، وcreate-instance. يقوم بتخزين الرموز بشكل منفصل لكل مضيف المصادقة، لذا فإن التبديل بين السحابات لا يعيد استخدام الرموز من سحابة أخرى.

مهم

قم بإقران مضيف السلطة ورابط URL الأساسي لـ Graph لنفس السحابة. إذا قمت بتجاوز أحدهما، فتجاوز الآخر بحيث تستهدف المصادقة واستدعاءات مستوى البيانات لـ Graph نفس البيئة.

نقاط نهاية خدمة Agent 365

يستدعي CLI خدمات Agent 365 لاكتشاف خوادم بروتوكول سياق النموذج (MCP)، وإدارة خوادم MCP، وتسجيل نقطة نهاية المراسلة الخاصة بالوكيل. قم بتكوين نقاط نهاية الخدمة هذه باستخدام متغيرات البيئة فقط. نقاط النهاية هذه لا تحتوي على حقول a365.config.json.

المتغير	Description
`A365_DISCOVER_ENDPOINT_<ENV>`	الرابط الكامل لنقطة الاكتشاف الخاصة بـ Agent 365 Tools. يستدعي CLI هذا الرابط لاكتشاف خوادم MCP. كما يستخدم مصدر الرابط لاستدعاءات خدمات Agent 365 ذات الصلة، بما في ذلك إدارة خوادم MCP وتسجيل نقطة نهاية المراسلة. القيمة الافتراضية هي `https://agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers`.
`A365_CREATE_ENDPOINT_<ENV>`	الرابط الكامل الذي يستدعيه CLI لتسجيل نقطة نهاية الرسائل الخاصة بالوكيل. هذه القيمة لها الأسبقية عَلَى أصل `A365_DISCOVER_ENDPOINT_<ENV>`.
`A365_DELETE_ENDPOINT_<ENV>`	الرابط الكامل الذي تستدعيه واجهة سطر الأوامر (CLI) لإزالة تسجيل نقطة نهاية المراسلة الخاصة بالوكيل. هذه القيمة لها الأسبقية عَلَى أصل `A365_DISCOVER_ENDPOINT_<ENV>`.

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

مهم

تعيين اسم البيئة وحده لا يحوّل مكالمات خدمة Agent 365 بعيدًا عن الخدمة التجارية. إذا لم تضبط A365_DISCOVER_ENDPOINT_<ENV>، فإن CLI ينادي خدمة Agent 365 التجارية، حتى في سحابة حكومة الولايات المتحدة.

إعداد GCC

GCC يستخدم مضيف السلطة التجارية ورابط Microsoft Graph الأساسي، لذا لا تحتاج إلى تجاوزهما. لمزيد من المعلومات، راجع عمليات نشر السحابة الوطنية في Microsoft Graph. قم بتعيين البيئة على gcc وتوجيه مكالمات خدمة الوكيل 365 إلى خدمة GCC.

في a365.config.json، اضبط environment الحقل:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "gcc",
  "messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
  "deploymentProjectPath": "."
}

ثم قم بتعيين متغيرات البيئة. الإعداد A365_ENVIRONMENT يشمل أيضا الأوامر التي لا تقرأ a365.config.json، مثل develop list-available. في باش، شغل الأوامر التالية:

export A365_ENVIRONMENT="gcc"
export A365_DISCOVER_ENDPOINT_GCC="https://gcc.agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers"

في Windows PowerShell، قم بتشغيل الأوامر التالية:

$env:A365_ENVIRONMENT = "gcc"
$env:A365_DISCOVER_ENDPOINT_GCC = "https://gcc.agent365.svc.cloud.microsoft/agents/v2/discoverMCPServers"

تكوين GCC High أو DoD

تستخدم GCC High وDoD مضيف السلطة الخاص بهما ورابط قاعدة Microsoft Graph:

السحابة	`environment` قيمة	مضيف جهة الإصدار (`authorityHost`)	عنوان URL الأساسي لـ Microsoft Graph (`graphBaseUrl`)
GCC High	`gcc-high`	`https://login.microsoftonline.us`	`https://graph.microsoft.us`
وزاره الدفاع	`dod`	`https://login.microsoftonline.us`	`https://dod-graph.microsoft.us`

هذه القيم مستمدة من المقالات التالية. تحقق منها لنقاط النهاية الحالية:

مستأجرو GCC High وDoD يستخدمون Azure Government. يستخدم Agent 365 CLI Azure CLI لبعض العمليات، مثل اكتشاف المستأجر، لذا قم بتسجيل الدخول إلى Azure CLI في Azure Government. للتعليمات، انظر الاتصال بـ Azure Government باستخدام Azure CLI. خدمات Azure في Azure Government تستخدم أيضا أسماء نطاق مختلفة عن Azure العالمية. على سبيل المثال، إذا استضفت الوكيل في "Azure App Service"، فإن نقطة نهاية الرسائل الخاصة بك تستخدم نطاق Azure Government. لرسم خريطة نقاط النهاية، انظر مقارنة Azure Government وAzure العالمي.

اضبط هذه القيم في a365.config.json أو مع متغيرات البيئة. المتغيرات التي تعتمد على نطاق البيئة لها الأولوية على الحقول المطابقة a365.config.json، لذا استخدمها لتجاوز التكوين المُودَع في المستودع لكل جهاز أو لكل خط أنابيب.

تكوين فِي a365.config.json

المثال التالي يستهدف GCC High:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "gcc-high",

  "authorityHost": "https://login.microsoftonline.us",
  "graphBaseUrl": "https://graph.microsoft.us",

  "messagingEndpoint": "https://your-app.azurewebsites.us/api/messages",
  "deploymentProjectPath": "."
}

التكوين باستخدام متغيرات البيئة

المثال التالي من باش يستهدف GCC High:

export A365_ENVIRONMENT="gcc-high"
export A365_AUTHORITY_HOST_GCC_HIGH="https://login.microsoftonline.us"
export A365_GRAPH_BASE_URL_GCC_HIGH="https://graph.microsoft.us"

المثال التالي لنظام Windows PowerShell يستهدف GCC High:

$env:A365_ENVIRONMENT = "gcc-high"
$env:A365_AUTHORITY_HOST_GCC_HIGH = "https://login.microsoftonline.us"
$env:A365_GRAPH_BASE_URL_GCC_HIGH = "https://graph.microsoft.us"

بالنسبة لوزارة الدفاع، قم بتعيين البيئة على dod، واستخدم اللاحقة DOD، واستخدم عنوان URL الأساسي لـ DoD Microsoft Graph.

إذا كانت خدمات Agent 365 متوفرة في السحابة الخاصة بك، قم أيضًا بتعيين A365_DISCOVER_ENDPOINT_<ENV> إلى نقطة الاكتشاف لتلك السحابة. وإلا، ينادي CLI خدمة Agent 365 التجارية. لمزيد من المعلومات، راجع نقاط نهاية الخدمة لـ Agent 365.

مرجع التهيئة

يسرد هذا القسم الخصائص a365.config.json والمتغيرات البيئية التي تتحكم في إعدادات السحابة.

a365.config.json الخصائص

الملكية	Description	مطلوب	Default
`environment`	اسم البيئة السحابية. استخدم `prod`، `gcc`، `gcc-high`، أو `dod`. تحدد هذه القيمة المتغيرات ذات النطاق البيئي التي تقوم واجهة سطر الأوامر بقراءتها ومورد إمكانية المراقبة الذي يستخدمه الإعداد.	No	`prod`
`authorityHost`	مضيف جهة مصادقة OAuth للسحابة المحددة. يجب أن تكون القيمة أصل HTTPS.	No	`https://login.microsoftonline.com`
`graphBaseUrl`	رابط القاعدة Microsoft Graph للسحابة المختارة. يجب أن تكون القيمة أصل HTTPS.	No	`https://graph.microsoft.com`

متغيرات البيئة

المتغير	Description
`A365_ENVIRONMENT`	اسم البيئة السحابية. يستخدم CLI هذه القيمة عندما لا يضبط `a365.config.jsonenvironment`، وللأوامر التي لا تقرأ `a365.config.json`. القيمة الافتراضية هي `prod`.
`A365_AUTHORITY_HOST_<ENV>`	مضيف سلطة OAuth. هذه القيمة تكون لها الأسبقية على `authorityHost` في `a365.config.json`.
`A365_GRAPH_BASE_URL_<ENV>`	عنوان URL الأساسي لـ Microsoft Graph. هذه القيمة تكون لها الأسبقية على `graphBaseUrl` في `a365.config.json`.
`A365_DISCOVER_ENDPOINT_<ENV>`	نقطة الاكتشاف لـ Agent 365 Tools. تستخدم CLI أيضًا مصدرها لمكالمات خدمة Agent 365 ذات الصلة.
`A365_CREATE_ENDPOINT_<ENV>`	رابط تسجيل نقطة نهاية المراسلة.
`A365_DELETE_ENDPOINT_<ENV>`	عنوان URL لإزالة نقطة نهاية المراسلة.
`A365_MCP_APP_ID_<ENV>`	معرّف تطبيق المورد الخاص بأداة Agent 365 الذي يستخدمه CLI للحصول على الرموز لخوادم الأدوات. معظم المطورين لا يحتاجون إلى تعيين هذا المتغير.

كيف يتم اشتقاق لاحقة البيئة

تشتق واجهة سطر الأوامر (CLI) اللاحقة <ENV> على كل متغير ذي نطاق بيئة من اسم بيئتك. تقوم واجهة سطر الأوامر بقص الاسم، وتستبدل كل حرف ليس حرفًا أو رقمًا بشرطة سفلية (_)، وتحوله إلى أحرف كبيرة. يصبح الاسم الفارغ PROD.

اسم البيئة	اللاحقة الموحّدة	مثال على متغير
`gcc`	`GCC`	`A365_DISCOVER_ENDPOINT_GCC`
`gcc-high`	`GCC_HIGH`	`A365_GRAPH_BASE_URL_GCC_HIGH`
`dod`	`DOD`	`A365_AUTHORITY_HOST_DOD`

يجب أن يتم تحليل اسم البيئة واللاحقة عَلَى المتغير إلى نفس القيمة الموحّدة. على سبيل المثال، A365_ENVIRONMENT=gcc-high يقترن مع A365_AUTHORITY_HOST_GCC_HIGH.

أذونات إمكانية المراقبة

بالنسبة لوكلاء Blueprint، a365 setup all لا يطلب إذن Agent365.Observability.OtelWrite في أي سحابة. يخوّل تسجيل Agent 365 مثيل عامل مسجل بتصدير بيانات تتبع الاستخدام عبر مسار الخدمة إلى الخدمة (S2S) مِن دون الحاجة إلى هذا الإذن. لمزيد مِن المعلومات، راجع أذونات إمكانية المراقبة.

يمنح إعداد زميل الذَّكَاءُ الاصْطِنَاعِيُّ والأمر a365 setup permissions bot الإذن Agent365.Observability.OtelWrite عَلَى مورد Agent 365 Observability للسحابة المحددة. إذا كان الوكيل يُصدّر بيانات القياس عن بُعد عبر المسار المفوض ويحتاج إلى هذا الإذن، استخدم معرف تطبيق المورد الخاص بسحابتك:

السحابة	معرف تطبيق موارد قابلية الملاحظة
تجاري	`9b975845-388f-4429-889e-eab1ef63949c`
مجلس التعاون الخليجي	`2c672ad5-b104-44ed-8069-bb68dd138546`
GCC High	`009c6bd0-82e4-4466-95b3-4c996521f3d7`
وزاره الدفاع	`a9e04047-c6a7-430b-a7ae-faf8f8eed1b7`

كانت الإصدارات السابقة من CLI تمنح دائمًا الإذن على مورد Observability التجاري. إذا قمت بإعداد زميل ذكاء اصطناعي فِي سحابة تابعة للحكومة الأمريكية باستخدام إصدار سابق، فقم بضبط بيئة السحابة الخاصة بك وأعد تشغيل البرنامج a365 setup all بحيث تمنح واجهة سطر الأوامر الإذن عَلَى مورد إمكانية المراقبة فِي سحابتك.

** تحقق من التكوين الخاص بك

بعد تكوين سحابة، شغّل أمر قراءة فقط وتأكد من أن واجهة سطر الأوامر تستخدم نقاط النهاية (endpoints) المتوقعة. على سبيل المثال:

شغّل الأمر develop list-available. يظهر الناتج البيئة ورابط نقطة النهاية التي يستدعيها ال CLI.
احصل على رمز مميز باستخدام الأمر develop get-token.

استكشاف أخطاء تكوين السحابة

الجدول التالي يوضح أخطاء تكوين السحابة الشائعة وكيفية حلها.

عَرَض	السبب	Resolution
`Authority host must be an HTTPS origin without a path, query, fragment, or user info.` (أو نفس الخطأ لعنوان URL الأساسي للرسم البياني)	يتضمن مضيف السلطة أو رابط URL الأساسي لـ Graph مسارًا أو سلسلة استعلام أو جزءًا.	استخدام أصل HTTPS مجرد. على سبيل المثال، استخدم `https://login.microsoftonline.us` بدلا من `https://login.microsoftonline.us/common/oauth2/v2.0/authorize`.
هناك خطأ يقول ذلك `AzureUSGovernment` أو أن سحابة Azure CLI لا تميز بين GCC Moderate (GCC)، GCC High، وDoD.	البيئة هي `AzureUSGovernment`، أو اكتشف الإعداد تلك السحابة من Azure CLI.	اضبط البيئة على `gcc`، `gcc-high`، أو `dod`.
يستدعي CLI خدمة Agent 365 التجارية في سحابة الحكومة الأمريكية.	`A365_DISCOVER_ENDPOINT_<ENV>` غير مضبوط، أو أن لاحقته لا تتطابق مع اسم البيئة.	اضبط `A365_DISCOVER_ENDPOINT_<ENV>` باللاحقة الخاصة ببيئتك.
يمنح الإعداد أذونات عَلَى مورد إمكانية المراقبة التجاري.	البيئة غير مضبوطة، لذا تستخدم واجهة سطر الأوامر `prod`.	تعيين بيئة السحابة وإعادة تشغيل الإعداد.
`PowerShell fallback is available only for commercial Graph and authority endpoints.`	فشل تسجيل الدخول في Microsoft Graph، ولا يمكن لـ CLI الرجوع إلى PowerShell `Connect-MgGraph` عند استخدام نقاط نهاية مخصصة.	حل مشكلة فشل تسجيل الدخول. على سبيل المثال، تأكد من أنك سجلت تطبيق العميل في سحابتك وأنك تسجل الدخول بحساب في المستأجر الخاص بسحابتك.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

تاريخ آخر تحديث في 2026-10-20