تكوين واجهة سطر الأوامر لـ 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 أو باستخدام متغيرات البيئة.

ملحوظة

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

Important

نقاط النهاية القابلة للتكوين لا تضمن توفر كل خدمة أو ميزة من 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.

Important

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

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

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

اسم البيئة

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

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

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

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

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

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

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

لا تقرأ واجهة سطر الأوامر هذه الإعدادات من المتغيرات غير اللاحقة مثل A365_GRAPH_BASE_URL.

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

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

Important

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

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

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

المتغير الوصف
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 مطلق. أضف مسارا إذا كانت نقطة النهاية بحاجة إلى ذلك، لكن لا تتضمن سلسلة استعلام أو جزء أو معلومات المستخدم.

Important

تعيين اسم البيئة وحده لا يحوّل مكالمات خدمة 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 الخصائص

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

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

المتغير الوصف
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> رابط إزالة نقطة نهاية المراسلة.
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.

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

أثناء الإعداد، يمنح CLI مخطط الوكيل الإذن 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 بحيث تمنح واجهة سطر الأوامر (CLI) الإذن على مورد الملاحظة الخاص بسحابتك.

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

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

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

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

عَرَض السبب القرار
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 عند استخدام نقاط نهاية مخصصة. حل مشكلة فشل تسجيل الدخول. على سبيل المثال، تأكد من أنك سجلت تطبيق العميل في السحابة الخاصة بك وأنك تسجل الدخول بحساب في مستأجر السحابة الخاصة بك.

المحتوى ذو الصلة

  • Last updated on