إعداد قالب تطبيق Snowflake في ChatGPT

استخدم هذا الدليل إذا كنت مسؤول مساحة عمل مشتركة في ChatGPT أو مستخدمًا لخطة ChatGPT Plus أو Pro وتريد ربط ChatGPT بـ Snowflake عبر خادم MCP تديره Snowflake.

تُجرى معظم خطوات الإعداد في Snowflake. بعد تجهيز Snowflake، أكمل اتصال قالب Snowflake في ChatGPT، ثم فعّل مكوّن Snowflake الإضافي الذي يستخدم هذا القالب.

• OAuth المدمج: عند توفره لحسابك في Snowflake وفي ChatGPT، استخدم تطبيق الشريك ChatGPT الذي يفعّله مسؤول Snowflake. سجّل الدخول إلى Snowflake باستخدام تسجيل الدخول الموحد (SSO) لمؤسستك إذا كان مُعدًّا. لا تحتاج إلى إدخال معرّف عميل أو سرّ عميل في ChatGPT. اتبع قسم «OAuth المدمج» أدناه.

• عميل OAuth مخصص: استخدم هذا المسار إذا كانت مؤسستك تشترط استخدام عميل OAuth خاص بها أو إذا لم يكن OAuth المدمج متاحًا. اتبع قسم «عميل OAuth مخصص» أدناه.

يتطلب كلا مسارَي OAuth إعداد خادم MCP وصلاحيات الكائنات الأساسية والوصول إلى الشبكة الموضحة أدناه، وهي متطلبات مشتركة بين المسارين. أكمل خطوات الإعداد المشتركة حتى نهاية قسم «إدخال تفاصيل خادم Snowflake في ChatGPT» قبل إعداد OAuth.

ما الذي ستُعدّه؟

ستنشئ خادم MCP تديره Snowflake ليكون نقطة النهاية التي يتصل بها موصّل ChatGPT. يحدد خادم MCP ما يلي:

• الإجراءات التي يمكن لـ ChatGPT استخدامها.

• بيانات Snowflake أو كائناتها التي يمكن لهذه الأدوات الوصول إليها.

• دور Snowflake الذي يستخدمه كل مستخدم لمنح التفويض.

• قاعدة بيانات Snowflake والمخطط واسم خادم MCP التي تحدد نقطة النهاية.

بعد ذلك، تُعدّ Snowflake - القالب الرسمي في ChatGPT باستخدام عنوان URL الكامل لخادم MCP المُدار. قد تعرض شاشة إعداد القالب عنوان URL في أربعة حقول منفصلة:

• بادئة مضيف Snowflake.

• قاعدة البيانات.

• المخطط.

• اسم خادم MCP.

لا يمكن لـ ChatGPT اكتشاف الأدوات واستخدامها إلا إذا كان خادم MCP يتيحها وكان دور Snowflake الذي يمنح المستخدم التفويض من خلاله يسمح بها.

قبل البدء

تحتاج إلى:

• صلاحيات مسؤول أو مالك مساحة عمل مشتركة في ChatGPT، أو اشتراك ChatGPT Plus أو Pro.

• صلاحيات في Snowflake تتيح إنشاء كائنات خادم MCP ومنح الصلاحيات.

• قاعدة بيانات Snowflake والمخطط اللذَين سيُنشأ فيهما خادم MCP.

• تحديد ما سيُسمح لـ ChatGPT باستخدامه، مثل Cortex Search أو Cortex Analyst أو SQL للقراءة فقط أو إجراء أو دالة محددة.

• دور Snowflake بأقل قدر من الصلاحيات اللازمة، ليستخدمه المستخدمون عند تفويض التطبيق.

• بادئة مضيف حساب Snowflake، بما فيها أي لاحقة للمنطقة أو السحابة.

إذا كان حساب Snowflake يقيّد الوصول من خلال سياسة شبكة أو قائمة بعناوين IP المسموح بها، فاطلب من مسؤول Snowflake السماح بالاتصالات الواردة من نطاقات عناوين IP الحالية للاتصالات الصادرة من موصّلات ChatGPT. تتغير هذه القائمة، وينبغي تحديثها باستمرار.

القيم المطلوب تجهيزها

• بادئة مضيف Snowflake: كل ما يسبق .snowflakecomputing.com في عنوان URL لحساب Snowflake.

• قاعدة البيانات: قاعدة البيانات التي تحتوي على خادم MCP.

• المخطط: المخطط الذي يحتوي على خادم MCP.

• اسم خادم MCP: اسم كائن خادم MCP في Snowflake.

• عنوان URL الكامل لخادم MCP المُدار، إذا طلبت شاشة إعداد ChatGPT عنوان URL.

• دور Snowflake: الدور الذي ينبغي أن يستخدمه المستخدمون عند تفويض التطبيق.

• قائمة الأدوات: كائنات Snowflake والإجراءات التي تريد أن يستخدمها ChatGPT.

تحديد ما يمكن لـ ChatGPT فعله

اختر فقط الإمكانات التي تريد إتاحتها. تشمل الخيارات الشائعة:

• البحث باستخدام Cortex Search للعثور على إجابات في بيانات Snowflake أو محتواها المفهرس.

• الإجابة عن الأسئلة باستخدام Cortex Analyst من خلال عرض دلالي معتمد.

• SQL للقراءة فقط لإتاحة الاستعلامات ضمن ضوابط محددة.

• وكيل Snowflake أو إجراء مخزّن أو دالة يعرّفها المستخدم (UDF) لسير عمل محدد.

إذا فعّلت SQL، فاجعله للقراءة فقط ما لم تكن مؤسستك قد راجعت صلاحية الكتابة ووافقت عليها.

فتح ورقة عمل في Snowflake

1. سجّل الدخول إلى تطبيق Snowflake.

2. انتقل إلى دور يتيح إنشاء خادم MCP ومنح صلاحيات الوصول.

3. انتقل إلى مساحات العمل.

   

4. أنشئ مساحة عمل تتضمن ملف SQL.

   

5. اضبط سياق مساحة العمل على قاعدة البيانات والمخطط اللذَين سيُنشأ فيهما خادم MCP.

   

إنشاء خادم MCP في Snowflake

سجّل الدخول إلى Snowflake بدور يتيح إنشاء خادم MCP ومنح صلاحيات الوصول. افتح ورقة عمل في قاعدة البيانات والمخطط اللذَين تريد إنشاء خادم MCP فيهما.

نفّذ عبارة مشابهة للمثال التالي. استبدل الأسماء بأسماء قاعدة البيانات والمخطط والخدمات والعروض والمستودع والخادم الخاصة بك في Snowflake.

CREATE MCP SERVER CHATGPT_SNOWFLAKE_MCP
FROM SPECIFICATION $$
tools:
- name: "support-search"
type: "CORTEX_SEARCH_SERVICE_QUERY"
identifier: "CHATGPT_APPS.TOOLS.SUPPORT_SEARCH_SERVICE"
title: "Support Search"
description: "Search support content for relevant customer issues."
- name: "revenue-analyst"
type: "CORTEX_ANALYST_MESSAGE"
identifier: "CHATGPT_APPS.TOOLS.REVENUE_SEMANTIC_VIEW"
title: "Revenue Analyst"
description: "Answer revenue questions using the approved semantic view."
- name: "sql-readonly"
type: "SYSTEM_EXECUTE_SQL"
title: "Read-only SQL"
description: "Run read-only SQL queries against approved Snowflake data."
config:
read_only: true
query_timeout: 600
warehouse: "CHATGPT_WH"
$$;

أسماء الأدوات وكائنات Snowflake في هذه العبارة مجرد أمثلة:

• تتيح support-search خدمة Cortex Search المحددة.

• تتيح revenue-analyst العرض الدلالي المحدد. أضف أدوات للعروض الأخرى حسب الحاجة.

• تتيح sql-readonly استخدام SQL للقراءة فقط مع المستودع المحدد.

استخدم أسماء ثابتة وواضحة الدلالة للأدوات حتى يتمكن ChatGPT من اختيار الأداة المناسبة. إنشاء خادم MCP لا يمنح تلقائيًا صلاحية الوصول إلى كائنات Snowflake الأساسية.

للاطلاع على خيارات إضافية للمواصفات، راجع: إنشاء خادم MCP تديره Snowflake.

منح صلاحيات Snowflake المناسبة

اختر دور Snowflake الذي سيمنح المستخدمون التفويض من خلاله، ثم امنح هذا الدور صلاحية الوصول إلى:

1. قاعدة البيانات والمخطط.

2. خادم MCP.

3. كل كائن أساسي تستخدمه الأدوات، مثل خدمة بحث أو عرض دلالي أو مستودع.

مثال:

GRANT USAGE ON DATABASE CHATGPT_APPS TO ROLE CHATGPT_CONNECTOR_ROLE;
GRANT USAGE ON SCHEMA CHATGPT_APPS.TOOLS TO ROLE CHATGPT_CONNECTOR_ROLE;
GRANT USAGE ON MCP SERVER CHATGPT_APPS.TOOLS.CHATGPT_SNOWFLAKE_MCP TO ROLE CHATGPT_CONNECTOR_ROLE;

GRANT USAGE ON CORTEX SEARCH SERVICE CHATGPT_APPS.TOOLS.SUPPORT_SEARCH_SERVICE TO ROLE CHATGPT_CONNECTOR_ROLE;
GRANT SELECT ON SEMANTIC VIEW CHATGPT_APPS.TOOLS.REVENUE_SEMANTIC_VIEW TO ROLE CHATGPT_CONNECTOR_ROLE;
GRANT USAGE ON WAREHOUSE CHATGPT_WH TO ROLE CHATGPT_CONNECTOR_ROLE;

إذا كان خادم MCP يتيح دالة يعرّفها المستخدم (UDF) أو إجراءً مخزّنًا أو وكيل Cortex، فامنح الصلاحيات المطلوبة لهذا الكائن أيضًا.

التحقق من جاهزية Snowflake

نفّذ:

SHOW MCP SERVERS IN SCHEMA CHATGPT_APPS.TOOLS;

ثم نفّذ:

DESCRIBE MCP SERVER CHATGPT_APPS.TOOLS.CHATGPT_SNOWFLAKE_MCP;

تأكد مما يلي:

• وجود الخادم في قاعدة البيانات والمخطط المتوقعَين.

• تطابق قائمة الأدوات مع ما أردت إتاحته.

• إشارة identifier لكل أداة إلى كائن Snowflake الصحيح.

• امتلاك الدور المستخدَم للاتصال صلاحية USAGE على خادم MCP.

• امتلاك الدور المستخدَم للاتصال الصلاحيات اللازمة على كل كائن أساسي.

إدخال تفاصيل خادم Snowflake في ChatGPT

1. في ChatGPT، انتقل إلى الحساب أو مساحة العمل المشتركة التي تريد إتاحة التطبيق فيها.

2. انتقل إلى الإعدادات > المكوّنات الإضافية للإعداد الشخصي، أو إلى إعدادات مساحة العمل المشتركة > المكوّنات الإضافية بصفتك مسؤول مساحة العمل المشتركة لإعداد التطبيق فيها.

3. ابحث عن Snowflake.

4. فعّل Snowflake - القالب الرسمي.

5. افتح Snowflake - القالب الرسمي، وأدخل اسمًا واضحًا للاتصال، ثم اختر اتصال.

6. أدخل عنوان URL الكامل لخادم MCP المُدار:

https://<snowflake_host_prefix>.snowflakecomputing.com/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{server}

مثال:

https://myorg-myaccount.azure.snowflakecomputing.com/api/v2/databases/CHATGPT_APPS/schemas/TOOLS/mcp-servers/CHATGPT_SNOWFLAKE_MCP

إذا كانت شاشة الإعداد تعرض إعدادات Snowflake في حقول منفصلة، فاستخدم القيم نفسها الواردة في عنوان URL:

بادئة مضيف Snowflake

استخدم كل ما يسبق .snowflakecomputing.com في عنوان URL لحسابك في Snowflake، بما فيه أي لاحقة للمنطقة أو السحابة.

على سبيل المثال، إذا كان عنوان URL للحساب يبدأ بما يلي:

https://myorg-myaccount.azure.snowflakecomputing.com

فبادئة المضيف هي:

myorg-myaccount.azure

قاعدة البيانات

أدخل قاعدة البيانات التي تحتوي على خادم MCP، مثل:

CHATGPT_APPS

المخطط

أدخل المخطط الذي يحتوي على خادم MCP، مثل:

TOOLS

اسم خادم MCP

أدخل اسم كائن خادم MCP في Snowflake، مثل:

CHATGPT_SNOWFLAKE_MCP

إعداد OAuth

اختر مسار OAuth المتاح لحسابك والذي يلبي متطلبات مؤسستك. يستخدم كلا المسارين خطوات إعداد خادم MCP المشتركة أعلاه، واختبارات الاتصال وضوابط الوصول أدناه.

في كلا مسارَي OAuth، عند استخدام session:role:all، تستخدم Snowflake الدور الافتراضي لكل مستخدم. يجب أن يكون الدور الافتراضي ضمن قائمة الأدوار المسموح بها في تكامل OAuth، إذا كانت مُعدّة، وألا يكون محظورًا. امتلاك دور آخر معتمد لا يعني اختياره تلقائيًا.

OAuth المدمج

قبل المتابعة، أكمل الأقسام المشتركة أعلاه لإنشاء خادم MCP ومنح الصلاحيات والتحقق من الخادم وإدخال تفاصيله في ChatGPT. هذا مطلوب حتى لو انتقلت مباشرةً إلى هذا القسم.

استخدم هذا المسار فقط عندما يكون تطبيق الشريك ChatGPT متاحًا لحسابك في Snowflake ويكون OAuth المدمج متاحًا في نافذة إعداد ChatGPT.

1. اطلب من مسؤول Snowflake تفعيل تكامل الشريك ChatGPT في حساب Snowflake نفسه الذي يستضيف خادم MCP. أعِد استخدام تكامل الشريك ChatGPT الموجود والمفعّل.

2. في نافذة إعداد ChatGPT، استخدم OAuth المدمج. لا تحتاج إلى إدخال معرّف عميل أو سرّ عميل أو تسجيل عنوان URL لمعاودة الاتصال.

3. تابع إلى قسم «الاتصال بـ Snowflake وإدارته» أدناه لتسجيل الدخول ومنح الموافقة وإعداد الوصول. ثم أكمل قسم «اختبار التطبيق»، بما في ذلك الاختبارات مع الأعضاء المسموح لهم بالوصول ممن لا يملكون صلاحيات مسؤول.

تنطبق على هذا المسار أيضًا آلية التعامل مع الدور الافتراضي وقائمة الأدوار المسموح بها والأدوار المحظورة الموضحة أعلاه.

عميل OAuth مخصص

قبل المتابعة، أكمل الأقسام المشتركة أعلاه لإنشاء خادم MCP ومنح الصلاحيات والتحقق من الخادم وإدخال تفاصيله في ChatGPT. هذا مطلوب حتى لو انتقلت مباشرةً إلى هذا القسم.

لاستخدام عميل OAuth مخصص، تحتاج إلى معرّف عميل وسرّ عميل من Snowflake. تنطبق على هذا المسار أيضًا آلية التعامل مع الدور الافتراضي وقائمة الأدوار المسموح بها والأدوار المحظورة الموضحة أعلاه.

1. في نافذة إعداد ChatGPT، اختر إعدادات OAuth المتقدمة > عميل OAuth يحدده المستخدم، وانسخ عنوان URL لمعاودة الاتصال الظاهر في ChatGPT كما هو تمامًا.

2. أنشئ تكامل أمان OAuth مخصصًا مع ضبط OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' وتعيين OAUTH_REDIRECT_URI إلى عنوان URL لمعاودة الاتصال نفسه تمامًا.

3. نفّذ العبارة التالية في Snowflake، مع كتابة اسم التكامل بأحرف كبيرة:

   SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('YOUR_INTEGRATION_NAME');

4. من نتيجة JSON، الصق قيمة oauth_client_id في معرّف عميل OAuth وقيمة oauth_client_secret في سرّ عميل OAuth في ChatGPT.

5. اضبط طريقة المصادقة لنقطة نهاية الرمز المميز على client_secret_basic.

بعد إدخال بيانات اعتماد العميل المخصص، تابع إلى قسمَي «الاتصال بـ Snowflake وإدارته» و«اختبار التطبيق» أدناه.

الاتصال بـ Snowflake وإدارته

1. في كلا مسارَي OAuth، اختر متابعة في نافذة إعداد ChatGPT نفسها، ثم سجّل الدخول إلى Snowflake وفوّض الاتصال. يمكنك استخدام تسجيل الدخول الموحد (SSO) لمؤسستك إذا كان مُعدًّا.

2. عند الإعداد لمساحة عمل مشتركة، اضبط سياسة تثبيت المكوّن الإضافي وصلاحيات الوصول بحسب الدور أو المجموعة للأعضاء الذين ينبغي أن يستخدموه. تحقق من تفعيل كلٍّ من Snowflake وSnowflake - القالب الرسمي.

3. يتولى مسؤولو مساحة العمل المشتركة إعداد وصول المستخدمين للأدوار التي ينبغي أن تستخدم Snowflake.

4. يتولى مسؤولو مساحة العمل المشتركة مراجعة التحكم في الإجراءات للأدوات المتاحة.

5. يتولى مسؤولو مساحة العمل المشتركة مراجعة أذونات التطبيق لتحديد متى يطلب ChatGPT موافقة الأعضاء قبل استخدام التطبيق.

تنطبق أذونات التطبيق هذه على محادثات ChatGPT. يستخدم وكلاء مساحة العمل المشتركة ضوابط خاصة بكل وكيل يحددها منشئه لتحديد إجراءات التطبيق المتاحة ومتى تُطلب موافقة المستخدمين النهائيين عليها. لمعرفة كيفية عمل الوكلاء، راجع: وكلاء مساحة العمل المشتركة في ChatGPT لخطتَي Enterprise وBusiness.

اختبار التطبيق

1. افتح محادثة، واختر Snowflake، واختبر الاتصال.

2. تأكد من أن ChatGPT يكتشف الأدوات التي أعددتها.

3. نفّذ أولًا إجراء قراءة منخفض المخاطر، مثل بحث أو استعلام للقراءة فقط في بيانات معتمدة.

4. تأكد من أن صلاحيات Snowflake تمنع الوصول خارج نطاق الدور والكائنات المعتمدة.

5. عند الإعداد لمساحة عمل مشتركة، اختبر الاتصال مع أعضاء مسموح لهم بالوصول ولا يملكون صلاحيات مسؤول، ولديهم أدوار افتراضية مختلفة في Snowflake. نجاح اتصال المسؤول لا يؤكد قدرة جميع الأعضاء على الاتصال.

بالنسبة لمسؤولي مساحة العمل المشتركة، لا يكفي تفعيل Snowflake وحده. إذا لم يُفعّل Snowflake - القالب الرسمي ويُربط، فقد يظهر المكوّن الإضافي للأعضاء على أنه معطّل.

عنوان URL لخادم MCP وآلية عمل OAuth

يتصل ChatGPT بعنوان URL الكامل لخادم MCP الذي تديره Snowflake:

https://<snowflake_host_prefix>.snowflakecomputing.com/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{server}

يستخدم ChatGPT بادئة مضيف Snowflake من عنوان URL هذا لتحديد نقطتَي نهاية OAuth التاليتين في Snowflake:

• التفويض: https://<snowflake_host_prefix>.snowflakecomputing.com/oauth/authorize

• الرمز المميز: https://<snowflake_host_prefix>.snowflakecomputing.com/oauth/token-request

لا تلصق عنوان URL لـ Snowsight، أو عنوان URL الأساسي لحساب Snowflake وحده، أو عنوان URL يتضمن أجزاء إضافية في المسار. يجب أن يتضمن عنوان URL لخادم MCP المسار /api/v2/databases/{database}/schemas/{schema}/mcp-servers/{server} وأن يطابق كائنات Snowflake لديك تمامًا.

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

Snowflake مفعّل للمسؤول لكنه معطّل لأحد الأعضاء

• تأكد من تفعيل كلٍّ من Snowflake وSnowflake - القالب الرسمي في إعدادات مساحة العمل المشتركة > المكوّنات الإضافية.

• افتح Snowflake - القالب الرسمي وأكمل خطوات اتصال الخاصة به. لا يكفي تفعيل القالب دون ربطه.

• افتح Snowflake وتأكد من ظهور القالب بوصفه التطبيق المطلوب له.

• تأكد من أن سياسة تثبيت المكوّن الإضافي تسمح بدور العضو الذي يواجه المشكلة أو مجموعته.

لم يُعثر على خادم MCP

• أعِد التحقق من عنوان URL الكامل لخادم MCP، أو من حقول القالب الأربعة إذا كانت شاشة الإعداد تطلبها.

• تأكد من وجود خادم MCP في قاعدة البيانات والمخطط المحددَين تمامًا.

لا تظهر أي أدوات في ChatGPT

• تأكد من أن مواصفات خادم MCP تتضمن أدوات.

• تأكد من أن الدور يمتلك صلاحية USAGE على خادم MCP.

تظهر الأداة لكنها تفشل عند استخدامها

• تأكد من أن الدور يمتلك الصلاحية المطلوبة على كائن Snowflake الأساسي، مثل خدمة البحث أو العرض الدلالي أو المستودع أو الإجراء أو الدالة التي يعرّفها المستخدم (UDF).

فشل أداة SQL

• تأكد من صحة اسم المستودع ومن أنه قيد التشغيل.

• تأكد من أن الدور يمتلك صلاحية USAGE على المستودع.

• تأكد من ضبط read_only: true إذا كنت تريد إتاحة القراءة فقط.

حُظر الدور المطلوب ALL صراحةً

اطلب من مسؤول Snowflake مقارنة دورك الافتراضي بالأدوار المسموح بها والمحظورة في تكامل OAuth. امتلاك دور آخر مسموح به لا يعني اختياره تلقائيًا. إذا كان ذلك مناسبًا، فغيّر الدور الافتراضي إلى دور معتمد وأعِد الاتصال. يؤثر تغيير دورك الافتراضي أيضًا في جلسات Snowflake خارج ChatGPT.

فشل التفويض

• تأكد من قدرة المستخدم على تسجيل الدخول إلى Snowflake.

• عند استخدام session:role:all، تأكد من أن تكامل OAuth يسمح بالدور الافتراضي للمستخدم.

• تأكد من أن الإعداد يستخدم تدفق OAuth الخاص بخادم MCP الذي تديره Snowflake.

• إذا كنت تستخدم عميل OAuth مخصصًا، فتأكد من تطابق معرّف العميل وسرّ العميل مع تكامل OAuth في Snowflake، ومن أن عنوان URI لإعادة التوجيه فيه يطابق تمامًا عنوان URL لمعاودة الاتصال الظاهر في ChatGPT.

  إذا كنت تستخدم OAuth المدمج، فاطلب من مسؤول Snowflake التحقق من توفر تكامل الشريك ChatGPT وتفعيله في الحساب الذي يستضيف خادم MCP.

سياسة شبكة Snowflake أو قائمة عناوين IP المسموح بها تحظر الموصّل

• اطلب من مسؤول Snowflake تحديث سياسة الشبكة أو قواعد الوصول في Snowflake.

• اسمح بالاتصالات الواردة من نطاقات عناوين IP الحالية للاتصالات الصادرة من موصّلات ChatGPT.

• أعدّ قائمة السماح هذه في Snowflake. وهي منفصلة عن قائمة عناوين IP المسموح بها لمساحة العمل المشتركة في ChatGPT.

• اجعل التحديثات من ملف JSON المنشور تلقائية متى أمكن، لأن النطاقات قد تتغير.

مشكلة في الاتصال تتعلق باسم المضيف

استخدم بادئة مضيف Snowflake الصحيحة. قد تتسبب أسماء مضيفي Snowflake التي تحتوي على شرطات سفلية في حدوث مشكلات؛ يُفضّل استخدام الشرطات العادية.

المراجع

• خادم MCP تديره Snowflake

• CREATE MCP SERVER

• DESCRIBE MCP SERVER

• SHOW MCP SERVERS