1. نظرة عامة
يمكنك استخدام Antigravity CLI في كلٍّ من بيئاتك المحلية والافتراضية. تتيح لك Antigravity الاستفادة من إمكانات Gemini مباشرةً في نافذة الأوامر على جهازك. من منظور الشبكات، عندما تستخدم Antigravity CLI، سيتم إجراء طلب إلى Gemini API من خلال عنوان IP الخاص بواجهة برمجة التطبيقات المتاح للجميع.
ماذا يحدث إذا أردت استخدام واجهة سطر الأوامر Antigravity على جهاز Google Compute Engine ولكنك تريد الاتصال بواجهة برمجة التطبيقات بشكل خاص؟ في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية ضبط نقطة نهاية Private Service Connect لواجهات Google APIs من أجل توجيه الزيارات إلى عنوان IP داخلي تحدّده.
ستكون عمليات الضبط مزيجًا من Terraform وgcloud ووحدة التحكّم.
في هذه الميزة الاختبارية، ستتعرّف على كيفية تنفيذ المهمة التالية:
- إعداد مثيل الجهاز الافتراضي وCloud NAT
- تثبيت Antigravity CLI والمصادقة
- ضبط نقطة نهاية Private Service Connect للاتصال بـ Googleapis
- التحقّق من مسار الاتصال بـ *.googleapis
- ضبط إدخالات نظام أسماء النطاقات اليدوية
في هذا الدرس التطبيقي، ستنشئ النمط التالي.
الشكل 1.

2. إعداد خدمات Google Cloud
إعداد البيئة بالسرعة التي تناسبك
- سجِّل الدخول إلى Google Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. إذا لم يكن لديك حساب على Gmail أو Google Workspace، عليك إنشاء حساب.



- اسم المشروع هو الاسم المعروض للمشاركين في هذا المشروع. وهي سلسلة أحرف لا تستخدمها Google APIs. ويمكنك تعديلها في أي وقت.
- رقم تعريف المشروع هو معرّف فريد في جميع مشاريع Google Cloud ولا يمكن تغييره بعد ضبطه. تنشئ Cloud Console تلقائيًا سلسلة فريدة، ولا يهمّك عادةً ما هي. في معظم دروس البرمجة، عليك الرجوع إلى رقم تعريف مشروعك (يُشار إليه عادةً باسم
PROJECT_ID). إذا لم يعجبك المعرّف الذي تم إنشاؤه، يمكنك إنشاء معرّف عشوائي آخر. يمكنك بدلاً من ذلك تجربة اسم من اختيارك ومعرفة ما إذا كان متاحًا. لا يمكن تغيير هذا الخيار بعد هذه الخطوة وسيظل ساريًا طوال مدة المشروع. - للعلم، هناك قيمة ثالثة، وهي رقم المشروع، تستخدمها بعض واجهات برمجة التطبيقات. يمكنك الاطّلاع على مزيد من المعلومات حول هذه القيم الثلاث في المستندات.
- بعد ذلك، عليك تفعيل الفوترة في Cloud Console لاستخدام موارد/واجهات برمجة تطبيقات Cloud. لن تكلفك تجربة هذا الدرس التطبيقي حول الترميز الكثير، إن وُجدت أي تكلفة على الإطلاق. لإيقاف الموارد وتجنُّب تحمّل تكاليف فوترة تتجاوز هذا البرنامج التعليمي، يمكنك حذف الموارد التي أنشأتها أو حذف المشروع. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
بدء Cloud Shell
على الرغم من إمكانية تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، ستستخدم في هذا الدرس التطبيقي حول الترميز Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.
من Google Cloud Console، انقر على رمز Cloud Shell في شريط الأدوات أعلى يسار الصفحة:

لن يستغرق توفير البيئة والاتصال بها سوى بضع لحظات. عند الانتهاء، من المفترض أن يظهر لك ما يلي:

يتم تحميل هذه الآلة الافتراضية مزوّدة بكل أدوات التطوير التي ستحتاج إليها. توفّر هذه الخدمة دليلًا منزليًا دائمًا بسعة 5 غيغابايت، وتعمل على Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إكمال جميع المهام في هذا الدرس العملي ضمن المتصفّح. لست بحاجة إلى تثبيت أي تطبيق.
3- إعداد البيئة باستخدام Terraform
سننشئ سحابة VPC مخصّصة تتضمّن قواعد جدار الحماية والشبكة الفرعية. افتح Cloud Console واختَر المشروع الذي ستستخدمه.
- افتح Cloud Shell في أعلى يسار وحدة التحكّم، وتأكَّد من ظهور رقم تعريف المشروع الصحيح في Cloud Shell، وأكِّد أي طلبات تظهر لك للسماح بالوصول.

- أنشئ مجلدًا باسم terraform-build وانتقِل إليه
mkdir terraform-build && cd terraform-build
- أنشئ ملف main.tf وملف variable.tf.
touch main.tf variable.tf
- انتقِل إلى طريقة عرض محرّر Cloud Shell. انقر على المحرّر، وتأكَّد من السماح بأي طلبات ضرورية ليتم تحميل الواجهة.
- بعد التحميل، انتقِل إلى ملف > فتح مجلد وانتقِل إلى /home/your-user-name/terraform-build وانقر على حسنًا لفتح المجلد في المحرّر.

- اختَر الملف variable.tf وأضِف ما يلي. استبدِل النص
your-project-id-hereبرقم تعريف مشروعك الفعلي بين علامتَي اقتباس.
variable "project_id" {
type = string
default = "your-project-id-here"
}
variable "network_id" {
type = string
default = "antigravity-vpc-net"
}
- بعد ذلك، افتح الملف main.tf. سنضيف بعض تعليمات Terraform البرمجية لتنفيذ إجراءات مختلفة كما هو موضّح أدناه.
تفعيل واجهات برمجة التطبيقات |
|
إنشاء شبكة VPC باسم python-net |
|
إضافة شبكة فرعية |
|
إضافة قاعدتَين لجدار الحماية |
|
- انسخ ما يلي وألصِقه في ملف main .tf.
resource "google_project_service" "default" {
for_each = toset([
"dns.googleapis.com",
"aiplatform.googleapis.com",
"servicedirectory.googleapis.com"
])
service = each.value
disable_on_destroy = false
}
resource "google_compute_network" "default" {
project = var.project_id
name = var.network_id
auto_create_subnetworks = false
mtu = 1460
routing_mode = "GLOBAL"
}
resource "google_compute_subnetwork" "default" {
name = "vm1-subnet"
ip_cidr_range = "192.168.100.0/24"
region = "us-east1"
stack_type = "IPV4_ONLY"
network = google_compute_network.default.id
}
resource "google_compute_firewall" "allow_icmp" {
name = "allow-icmp-${google_compute_network.default.name}"
network = google_compute_network.default.id
project = var.project_id
allow {
protocol = "icmp"
}
source_ranges = ["0.0.0.0/0"]
target_tags = ["allow-icmp"]
}
resource "google_compute_firewall" "allow_ssh" {
name = "allow-ssh-${google_compute_network.default.name}"
network = google_compute_network.default.id
project = var.project_id
allow {
protocol = "tcp"
ports = ["22"]
}
source_ranges = ["0.0.0.0/0"]
target_tags = ["allow-ssh"]
}
- ارجع إلى وحدة طرفية Cloud Shell وتأكَّد من أنّك في الدليل terraform-build
cd terraform-buildونفِّذ الأوامر التالية
terraform init
تتم تهيئة دليل العمل. تنزّل هذه الخطوة موفّري الخدمات المطلوبين للإعدادات المحدّدة.
terraform plan
تُنشئ خطة تنفيذ توضّح الإجراءات التي سيتّخذها Terraform لنشر البنية الأساسية.
- لإنشاء الموارد، شغِّل الأمر
terraform applyواكتبyesلتشغيله.
4. المهمة رقم 2 إنشاء بوابة NAT وأجهزة افتراضية باستخدام Terraform
علينا منح إذن بالوصول الخارجي إلى الإنترنت، لذا لننشئ بوابة Cloud NAT ونرفقها.
- افتح Cloud Shell، وانتقِل إلى مجلد terraform-build وأنشئ الملفات التالية (إجمالي ثلاثة ملفات). سنعدّل هذه المعلومات لاحقًا.
touch nat-vm.tf psc.tf dns.tf
- انتقِل إلى عرض محرّر Cloud Shell واختَر الملف nat-vm.tf وأضِف رمز Terraform التالي. سيؤدي ذلك إلى إنشاء بوابة NAT وجهازَين افتراضيَّين.
Terraform nat-vm.tf
resource "google_compute_router" "default" {
name = "outbound-nat"
region = "us-east1"
network = google_compute_network.default.id
bgp {
asn = 64514
}
}
resource "google_compute_router_nat" "default" {
name = "outbound-gw"
router = google_compute_router.default.name
region = google_compute_router.default.region
nat_ip_allocate_option = "AUTO_ONLY"
source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"
log_config {
enable = true
filter = "ERRORS_ONLY"
}
}
resource "google_compute_instance" "vm1" {
name = "cli-vm"
zone = "us-east1-b"
machine_type = "n2-standard-2"
boot_disk {
initialize_params {
image = "debian-cloud/debian-12"
}
}
network_interface {
subnetwork = google_compute_subnetwork.default.id
stack_type = "IPV4_ONLY"
}
tags = ["allow-ssh", "allow-icmp"]
metadata_startup_script = <<-EOF
sudo apt-get update
EOF
}
resource "google_compute_instance" "vm2" {
name = "monitor-vm"
zone = "us-east1-b"
machine_type = "n2-standard-2"
boot_disk {
initialize_params {
image = "debian-cloud/debian-12"
}
}
network_interface {
subnetwork = google_compute_subnetwork.default.id
stack_type = "IPV4_ONLY"
}
tags = ["allow-ssh", "allow-icmp"]
metadata_startup_script = <<-EOF
sudo apt-get update
sudo apt-get install python3 python3-dev python3-venv -y
sudo apt-get install tcpdump dnsutils -y
EOF
}
- انتقِل إلى وحدة طرفية Cloud Shell، وتأكَّد من أنّك في المجلد terraform-build، ثم شغِّل
terraform planسيظهر لك أنّه ستتم إضافة 4 عناصر، ثم شغِّلterraform applyواكتبyesلإنشاء بوابة NAT وجهازَين افتراضيَين.
5- المهمة رقم 3 ضبط الأجهزة الافتراضية لواجهة سطر الأوامر واختبارها
- انتقِل إلى مثيلات الأجهزة الافتراضية. اختَر الجهاز الافتراضي الذي يبدأ بـ cli-vm. اختَر SSH.
- بعد إنشاء اتصال SSH، من المفترض أن تتمكّن من الوصول إلى الجهاز الظاهري. لننشئ مجلدًا لاستخدامه عند تشغيل Gemini CLI.
mkdir antigravitycli && cd antigravitycli
- لتثبيت Antigravity CLI، استخدِم ما يلي
curl -fsSL https://antigravity.google/cli/install.sh | bash && source ~/.bashrc
التحقّق من الإصدار
agy --version
- لنُسجّل الدخول ونثبت ملكية الحساب لنتمكّن من إجراء بعض الاختبارات لاحقًا.
agy
- اختَر الخيار 1
Google OAuth. لنُجري الآن عملية المصادقة.
- بعد ذلك، انسخ عنوان URL الذي يظهر في البداية مع https:// وافتح علامة تبويب جديدة في نافذة متصفح المختبر والصِق عنوان URL. قبول الطلبات

- عند ظهور الرسالة التالية، انقر على "نسخ إلى الحافظة" (copy to clipboard)، ثم ارجع إلى جلسة cli-vm وأدخِل الرمز الذي نسخته في الحقل أدخِل رمز التفويض: (Enter authorization code:)، ثم اضغط على Enter للمصادقة.

- ارجع إلى جلسة الجهاز الظاهري cli-vm، وفي الحقل Enter authorization code: (أدخِل رمز التفويض:)، ألصِق الرمز الذي نسخته واضغط على Enter للمصادقة.

- ستظهر لك الشاشة التي يمكنك من خلالها تخصيص الاتفاقية وقبولها والانتقال إلى دليل المنزل. حدِّد الخيارات المناسبة لإكمالها.


- بعد إكمالها، يمكنك البدء باستخدام Antigravity CLI

رصد مسار الزيارات إلى Gemini من خلال جهاز افتراضي (VM) للرصد
- انتقِل إلى مثيلات الأجهزة الافتراضية. اختَر الجهاز الظاهري الذي يبدأ بـ monitor-vm. اختَر SSH.
- بعد استخدام بروتوكول SSH في monitor-vm، من المفترض أن يكون لديك إذن الوصول
- لنستخدِم الأمر
digلاختبار مسار الاتصال بواجهة Gemini API. سنستخدم us-east1-aiplatform.googleapis.com
dig us-east1-aiplatform.googleapis.com
من المفترض أن يظهر لك شيء مشابه (سيختلف العنوان). يُرجى العِلم أنّ المسار يتم عبر عناوين IP العامة لأنّ واجهة برمجة التطبيقات هي واجهة برمجة تطبيقات عامة.
عدم النسخ
; <<>> DiG 9.18.33-1~deb12u2-Debian <<>> us-east1-aiplatform.googleapis.com ;; global options: +cmd ;; Got answer: ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 58905 ;; flags: qr rd ra; QUERY: 1, ANSWER: 14, AUTHORITY: 0, ADDITIONAL: 1 ;; OPT PSEUDOSECTION: ; EDNS: version: 0, flags:; udp: 65494 ;; QUESTION SECTION: ;us-east1-aiplatform.googleapis.com. IN A ;; ANSWER SECTION: us-east1-aiplatform.googleapis.com. 300 IN A 216.239.38.223 us-east1-aiplatform.googleapis.com. 300 IN A 216.239.34.223 us-east1-aiplatform.googleapis.com. 300 IN A 216.239.36.223 us-east1-aiplatform.googleapis.com. 300 IN A 216.239.32.223
- لنُجرِ الآن اختبارًا سريعًا
pingلمعرفة ما إذا كان بإمكاننا الاتصال بـ Gemini API. سيستخدم هذا الأمر 4 عمليات ping على us-east1-aiplatform.googleapis.com، وبالتالي سنحصل على ردّ من العنوان العام لواجهة برمجة التطبيقات.
ping -c 4 us-east1-aiplatform.googleapis.com
- سنعود لاختبار هذه الآلة الافتراضية لاحقًا. أغلِق جلسة SSH لنتابع.
6. المهمة رقم 4 إنشاء نقطة نهاية PSC إلى googleapis باستخدام Terraform
لتفعيل الاتصال الخاص بنقطة نهاية Vertex API، سننشئ نقطة نهاية Private Service Connect لواجهات Google APIs. سيسمح لنا ذلك باستخدام عنوان IP خاص نحدّده لتوجيه الزيارات إلى واجهات Google APIs التي نحتاج إليها، وفي هذه الحالة Vertex.
- افتح Cloud Shell في طريقة عرض المحرِّر إذا لم يكن مفتوحًا من قبل. سننشئ ما يلي:
- أنشئ عنوان IP لنقطة نهاية PSC 10.10.100.250 (
resource "google_compute_global_address" "default") - إنشاء نقطة نهاية PSC لواجهات Google APIs (
resource "google_compute_global_forwarding_rule" "default")
افتح الملف psc.tf في المجلد terraform-build. أضِف الرمز التالي إلى الملف.
ملف Terraform psc.tf
resource "google_compute_global_address" "default" {
name = "gemini-ip"
purpose = "PRIVATE_SERVICE_CONNECT"
network = google_compute_network.default.id
address_type = "INTERNAL"
address = "10.10.100.250"
}
resource "google_compute_global_forwarding_rule" "default" {
name = "pscgemini"
target = "all-apis"
network = google_compute_network.default.id
ip_address = google_compute_global_address.default.id
load_balancing_scheme = ""
service_directory_registrations {
namespace = "googleapis"
service_directory_region = "us-east1"
}
}
- انتقِل إلى نافذة Cloud Shell، وتأكَّد من أنّك في المجلد
terraform-build. ثم شغِّلterraform initثم شغِّلterraform planسيظهر لك أنّه ستتم إضافة عنصرَين،
ثم شغِّلterraform applyواكتبyesلإنشاء نقطة نهاية لواجهات Google APIs الخاصة بـ IP وPSC. - التحقّق من توفّر نقطة النهاية
gcloud compute addresses list --filter="name=( 'gemini-ip' ...)"
gcloud compute forwarding-rules describe pscgemini --global
7. المهمة رقم 5 إنشاء إدخال يدوي لنظام أسماء النطاقات إلى googleapis باستخدام Terraform
يمكنك إنشاء إدخال يدوي لنظام أسماء النطاقات (DNS) للإشارة إلى نقطة نهاية Private Service Connect (PSC) باستخدام نظام أسماء النطاقات الخاص. سيؤثّر ذلك في جميع الشبكات التي تحدّدها له.
- انتقِل إلى "خدمات الشبكة" واختَر Cloud DNS.
- في المناطق، من المفترض أن تظهر منطقة تم إنشاؤها تلقائيًا لخدمة Private Service Connect لواجهات Google APIs، مع دليل خدمة لنوع المنطقة. يمكن استخدام هذا العنوان للاتصال بنقطة نهاية PSC بالتنسيق **SERVICE-ENDPOINT.p.googleapis.com مثال:
aiplatform-pscgemini.p.googleapis.com - في هذه الحالة، نريد إنشاء إدخال نظام أسماء نطاقات خاص يدويًا. ستكون الإعدادات على النحو التالي
- أنشئ منطقة نظام أسماء نطاقات خاصًا باسم "googleapis-private" لـ "googleapis.com" واقتصر على شبكة "antigravity-vpc-net".
- أضِف سجلّ A لربط "googleapis.com" بعنوان IP "10.10.100.250".
- أضِف سجلّ CNAME لإعادة توجيه جميع النطاقات الفرعية من "googleapis.com" (مثل www.googleapis.com) إلى "googleapis.com".
- افتح Cloud Shell في طريقة عرض المحرِّر إذا لم يكن مفتوحًا من قبل. افتح الملف dns.tf في مجلد terraform-build. أضِف الرمز التالي إلى الملف.
Terraform dns.tf
resource "google_dns_managed_zone" "private_zone" {
name = "googleapis-private"
dns_name = "googleapis.com."
visibility = "private"
project = var.project_id
private_visibility_config {
networks {
network_url = google_compute_network.default.id
}
}
}
resource "google_dns_record_set" "a_record" {
name = "googleapis.com."
type = "A"
ttl = 300
managed_zone = google_dns_managed_zone.private_zone.name
project = var.project_id
rrdatas = ["10.10.100.250"]
}
resource "google_dns_record_set" "cname_record" {
name = "*.googleapis.com."
type = "CNAME"
ttl = 300
managed_zone = google_dns_managed_zone.private_zone.name
project = var.project_id
rrdatas = ["googleapis.com."]
}
- انتقِل إلى نافذة Cloud Shell، وتأكَّد من أنّك في المجلد
terraform-build. بعد ذلك، شغِّلterraform plan، وسيظهر لك العناصر التي ستتم إضافتها،
ثم شغِّلterraform applyواكتبyesلإنشاء إدخال نظام أسماء النطاقات الخاص. - من المفترض أن يظهر الإعداد مع سجلّ A وCNAME على النحو التالي

- بعد ذلك، نتحقّق من إمكانية الاتصال مع هذه التغييرات على monitor-vm.
8. المهمة 7. تأكيد إمكانية الاتصال بنقطة النهاية من خلال عنوان IP
لنربط حسابك باستخدام نقطة النهاية الخاصة للاتصال بـ Gemini.
- انتقِل إلى مثيل الجهاز الافتراضي monitor-vm. اختَر SSH وادخل إلى الجهاز الافتراضي باستخدام SSH
- تحقَّق من مسار الاتصال إلى us-east1-aiplatform.googleapis.com باستخدام الأمر
ping. سيؤدي ذلك إلى إرسال طلب اختبار الاتصال إلى عنوان IP في نظام أسماء النطاقات الخاص، وهو سجلّ A لـ googleapis. عنوان IP هذا هو نقطة نهاية PSC، ولن تنجح عمليات اختبار الاتصال.
ping -c 2 us-east1-aiplatform.googleapis.com
- تحقَّق من مسار الاتصال إلى us-east1-aiplatform.googleapis.com باستخدام الأمر
dig. يجب أن يكون هذا هو عنوان IP لنقطة نهاية PSC (10.10.100.250).
dig us-east1-aiplatform.googleapis.com

- بعد اكتمال العملية، يمكنك إغلاق جلسة SSH الخاصة بـ monitor-vm.
- انتقِل إلى مثيل الجهاز الافتراضي cli-vm. اختَر SSH وادخل إلى الجهاز الافتراضي باستخدام SSH
- يمكننا الآن تنفيذ TCP dump على cli-vm. سنحتاج إلى فتح جلستَي SSH على الجهاز الظاهري نفسه. ستنفّذ إحدى الجلسات الأمر tcpdump، بينما سنستخدم واجهة سطر الأوامر في Gemini في الجلسة الأخرى.
- اكتب الأمر التالي للاطّلاع على إمكانية الاتصال في tcpdump
sudo tcpdump -i any port 53 -n or host us-east1-aiplatform.googleapis.com
- الآن، سجِّل الدخول إلى الجلسة التالية على cli-vm باستخدام بروتوكول SSH.
- انتقِل إلى مجلد antigravitycli
cd antigravitycli - فعِّل Antigravity CLI عن طريق كتابة
agy - اطرح السؤال التالي:
what color is the sky?لإنشاء طلب إلى Gemini API

- اضغط على Enter لتنفيذ الأمر والاطّلاع على النتيجة.
- انتقِل مرة أخرى إلى الجلسة الأولى على cli-vm. من المفترض أن تظهر لك نتيجة tcpdump. ستلاحظ أنّ عنوان IP الخاص بالجهاز الظاهري يستخدم عنوان IP الخاص بنقطة نهاية PSC للاتصال بواجهة Gemini API.

إغلاق جميع جلسات SSH لأجهزة VM
9- تنظيف
- انتقِل إلى Cloud Shell وتأكَّد من أنّك في الدليل terraform-build
cd terraform-build، ثم نفِّذ الأمر التاليterraform destroyواكتبyes، وستتم إزالة جميع الموارد التي أنشأتها في مشروعك باستخدام Terraform.
10. تهانينا
تهانينا، لقد تمكّنت من الاتصال بواجهة Antigravity CLI باستخدام عنوان واجهة برمجة التطبيقات العامة وبشكل خاص باستخدام نقطة نهاية Private Service Connect لواجهات Google APIs. يمكن أن توسّع هذه الوظيفة إمكانية الاتصال الخاص بواجهات برمجة التطبيقات إلى بيئة السحابة الإلكترونية المحلية أو غيرها من البيئات السحابية المرتبطة من خلال (Interconnect وCross-Cloud Interconnect وVPC).
الخطوات التالية / مزيد من المعلومات
يمكنك الاطّلاع على مزيد من المعلومات في مستندات واجهة سطر الأوامر Antigravity.
الدرس التطبيقي التالي
يمكنك مواصلة رحلتك مع Google Cloud، والاطّلاع على هذه المختبرات الأخرى في Google Cloud: