۱. مقدمه
نقطه پایانی API گوگل
رابطهای برنامهنویسی کاربردی (API) گوگل کلود انواع مختلفی از نقاط پایانی را برای دسترسی به سرویسها ارائه میدهند که عمدتاً در نحوه مدیریت مسیریابی درخواست، محل ذخیرهسازی دادهها و جداسازی منطقهای متفاوت هستند.
لطفاً مستندات محصول را در مورد انواع نقاط پایانی API بررسی کنید.
در اینجا به تفکیک نقاط پایانی جهانی، منطقهای و مکانی آمده است:
- نقاط پایانی جهانی
- قالب: {service}.googleapis.com (مثلاً storage.googleapis.com)
- شرح: این نقاط پایانی یک نقطه دسترسی سراسری و واحد به یک سرویس ارائه میدهند. آنها منطقهای را در URL مشخص نمیکنند.
- مسیریابی: درخواستها توسط Global Google Front Ends (GFE) و Global Service Load Balancing مسیریابی میشوند و معمولاً ترافیک را به نزدیکترین منطقه سالم هدایت میکنند تا تأخیر به حداقل برسد.
- خاتمه TLS: در نزدیکترین GFE به کلاینت رخ میدهد، که ممکن است خارج از منطقه Google Cloud باشد که دادهها یا منابع در آن قرار دارند.
- اقامت دادهها: هیچ تضمینی برای دادههای در حال انتقال ارائه نمیشود. دادهها ممکن است پس از رمزگشایی در GFE از مرزهای منطقهای عبور کنند.
- جداسازی منطقهای: محدود. در حالی که backendها اغلب منطقهای هستند، نقطه ورود و متعادلسازی بار جهانی هستند، به این معنی که مشکلات در یک بخش از زیرساخت جهانی میتواند به طور بالقوه بر خدمات در مناطق دیگر تأثیر بگذارد.
- مورد استفاده: دسترسی عمومی که در آن تأخیر کم برای کاربران پراکنده جغرافیایی کلیدی است و ماندن دقیق دادهها در حین انتقال نگرانی اصلی نیست.
- نقاط پایانی منطقهای (REP)
- قالب: {service}.{location}.rep.googleapis.com (مثلاً storage.us-east1.rep.googleapis.com)
- شرح: این موارد به گونهای طراحی شدهاند که جداسازی منطقهای قوی و تضمینهای ماندگاری دادهها را ارائه دهند. مکان (یک منطقه خاص Google Cloud) به عنوان یک زیردامنه مشخص میشود. این استاندارد مدرن است و جایگزین نقاط پایانی مکانی میشود.
- مسیریابی: از یک پشته frontend کاملاً منطقهای، شامل متعادلکنندههای بار خارجی منطقهای و متعادلکننده بار سرویس منطقهای استفاده میکند. کل مسیر درخواست، از DNS تا backend سرویس، در منطقه مشخص شده باقی میماند.
- خاتمه TLS: در منطقه مشخص شده در متعادل کننده های بار خارجی منطقه ای رخ می دهد.
- اقامت دادهها: تضمین میکند که دادهها چه در زمان انتقال و چه در زمان استفاده، در محدوده تعیینشده باقی میمانند و الزامات سختگیرانه انطباق و حاکمیت را برآورده میکنند.
- انزوای منطقهای: قوی. خرابی در زیرساختهای فرانتاند یک منطقه، مناطق دیگر را تحت تأثیر قرار نمیدهد.
- مورد استفاده: برنامههایی که نیاز به نگهداری دقیق دادهها، جداسازی منطقهای بالا و انطباق دارند.
لطفاً توجه داشته باشید که هر API گوگل دارای نقطه پایانی منطقهای نیست و برای اطلاع از تمام نقاط پایانی منطقهای پشتیبانی شده، اینجا را بررسی کنید.
نقاط پایانی منطقهای چند منطقهای (mREP) نیز نقاط پایانی منطقهای هستند، مانند ایالات متحده آمریکا، اتحادیه اروپا (اتحادیه اروپا) و غیره (مثلاً storage.us.rep.googleapis.com)
- نقاط پایانی مکانی (LEP)
- قالب: {location}-{service}.googleapis.com (مثلاً، us-east1-storage.googleapis.com)
- شرح: این نقاط پایانی، رویکردی قدیمیتر برای ارائه دسترسی مبتنی بر مکان بودند. مکان بخشی از نام میزبان اصلی است. توجه: نقاط پایانی منطقهای (Regional Endpoints) جایگزین نقاط پایانی مکانی (Locational Endpoints) میشوند.
- مسیریابی: هنوز به Front End های جهانی گوگل متکی است.
- خاتمه TLS: معمولاً در GFE رخ میدهد، که ممکن است در ناحیه مشخص شده در نام میزبان نباشد.
- اقامت دادهها: نمیتوان تضمین کرد که دادهها در طول انتقال ترافیک از اینترنت عمومی در منطقه مشخصشده باقی بمانند.
- جداسازی منطقهای: از نقاط پایانی منطقهای ضعیفتر است زیرا از زیرساختهای فرانتاند جهانی استفاده میکنند.
- مورد استفاده: از گذشته برای برخی سناریوهای دسترسی منطقهای استفاده میشده، اما اکنون به دلیل تضمینهای قویتر، استفاده از نقاط پایانی منطقهای (Regional Endpoints) به طور کلی توصیه نمیشود.
اتصال سرویس خصوصی برای API گوگل
اتصال سرویس خصوصی قابلیتی از شبکه گوگل کلود است که به مصرفکنندگان اجازه میدهد به سرویسهای تولیدکننده دسترسی داشته باشند. این شامل قابلیت اتصال به APIهای گوگل از طریق یک نقطه پایانی خصوصی است که در VPC کاربر میزبانی میشود.
نحوه استفاده از نقطه پایانی PSC برای دسترسی به API گوگل:
- نقطه پایانی PSC برای API جهانی گوگل
- نقطه پایانی PSC برای API منطقهای گوگل
- شما از نقطه پایانی PSC برای API جهانی گوگل برای دسترسی خصوصی به API مکانی گوگل استفاده میکنید.
نحوه استفاده از backend PSC برای دسترسی به Google API:
- پس زمینه PSC برای API جهانی گوگل
- پس زمینه PSC برای API منطقهای گوگل
- شما از PSC backend برای Global Google API برای دسترسی خصوصی به Locational Google API استفاده میکنید.
Cloud Run ترافیک را به شبکه VPC ارسال میکند
خروجی مستقیم VPC، زیرساخت بهبود یافته و پیکربندی خروجی VPC سادهتری را برای Cloud Run به ارمغان میآورد، از جمله مزایای زیر:
- راهاندازی : سرویسها و کارهای Cloud Run میتوانند بدون سربار مدیریت یک رابط Serverless VPC Access، ترافیک را به شبکه VPC ارسال کنند.
- هزینه : شما فقط هزینه ترافیک شبکه را پرداخت میکنید که درست مانند خود سرویس، به صفر میرسد.
- امنیت : شما میتوانید از تگهای شبکه مستقیماً در نسخههای سرویس برای امنیت شبکه دقیقتر استفاده کنید.
- عملکرد : تأخیر کمتر، توان عملیاتی بالاتر.
شما میتوانید سرویس، تابع، کار یا مجموعه کارگر Cloud Run خود را طوری فعال کنید که با استفاده از خروجی مستقیم VPC، تمام ترافیک را به شبکه VPC ارسال کند.
۲. آنچه یاد خواهید گرفت
- نحوه ایجاد یک نقطه پایانی PSC برای API جهانی گوگل.
- نحوه ایجاد یک نقطه پایانی PSC برای API منطقهای گوگل.
- نحوه تغییر نقطه پایانی API در کد Cloud Run و پیکربندی شبکه برای خروجی.
۳. معماری کلی آزمایشگاه

۴. مراحل آمادهسازی
نقشهای IAM مورد نیاز برای کار در آزمایشگاه
شما با اختصاص نقشهای IAM مورد نیاز به حساب GCP در سطح پروژه شروع میکنید.
- مدیر شبکه محاسباتی (
roles/compute.networkAdmin) این نقش به شما کنترل کامل منابع شبکه Compute Engine را میدهد. - مدیر ثبت وقایع (
roles/logging.admin) این نقش به شما امکان دسترسی به تمام مجوزهای ثبت وقایع و مجوزهای وابسته را میدهد. - مدیر استفاده از سرویس (
roles/serviceusage.serviceUsageAdmin) این نقش به شما امکان فعال، غیرفعال کردن و بررسی وضعیت سرویس، بررسی عملیات و سهمیه مصرف و صدور صورتحساب برای یک پروژه مصرفکننده را میدهد. - مدیر DNS (
roles/dns.admin) این نقش به شما دسترسی خواندن و نوشتن به تمام منابع Cloud DNS را میدهد. - مدیر Cloud Run (
roles/run.admin) این نقش به شما کنترل کامل بر تمام منابع Cloud Run را میدهد. - مدیر ذخیرهسازی (
roles/storage.admin) این نقش به شما کنترل کامل اشیاء و سطلها را میدهد.
فعال کردن APIها
در داخل Cloud Shell، مطمئن شوید که پروژه شما به درستی پیکربندی شده است و متغیرهای محیطی خود را تنظیم کنید.
درون Cloud Shell، موارد زیر را انجام دهید:
gcloud auth login
gcloud config set project <your project id>
export project_id=<your project id>
export region=<your region>
export zone=$region-a
echo $project_id
echo $region
تمام API های لازم گوگل را در پروژه فعال کنید. در داخل Cloud Shell، موارد زیر را انجام دهید:
gcloud services enable \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
run.googleapis.com \
compute.googleapis.com \
dns.googleapis.com \
servicedirectory.googleapis.com \
networkconnectivity.googleapis.com
ایجاد VPC
در پروژه، یک شبکه VPC با حالت زیرشبکه سفارشی ایجاد کنید. موارد زیر را در Cloud Shell انجام دهید:
gcloud compute networks create mynet \
--subnet-mode=custom
ایجاد زیرشبکهها
در داخل Cloud Shell، برای ایجاد یک زیرشبکه IPV4، موارد زیر را انجام دهید:
gcloud compute networks subnets create mysubnet \
--network=mynet \
--range=10.0.0.0/24 \
--region=$region
ایجاد Cloud NAT و Cloud Router
Cloud NAT برای اتصال کارهای Cloud Run به وبسایتهای خارجی استفاده میشود.
gcloud compute routers create $region-cr \
--network=mynet \
--region=$region
gcloud compute routers nats create $region-nat \
--router=$region-cr \
--region=$region \
--nat-all-subnet-ip-ranges \
--auto-allocate-nat-external-ips
۵. ایجاد نقطه پایانی PSC برای فضای ذخیرهسازی ابری
شما دو نقطه پایانی PSC برای Cloud Storage ایجاد خواهید کرد، یکی برای محدوده جهانی و دیگری برای محدوده منطقهای.
ایجاد نقطه پایانی PSC از محدوده سراسری
با Private Service Connect، میتوانید با استفاده از آدرسهای IP داخلی سراسری در شبکه VPC خود، نقاط پایانی خصوصی Global Scoped ایجاد کنید.
شما باید یک آدرس IP منحصر به فرد که در VPC شما تعریف نشده است، اختصاص دهید. لطفاً به سند مربوط به این الزام آدرس IP مراجعه کنید.
در داخل Cloud Shell، برای ایجاد یک آدرس IP، موارد زیر را انجام دهید. لطفاً –addresses=<pscendpointip> را به آدرس IP که اختصاص دادهاید تغییر دهید.
gcloud compute addresses create pscglobalip \
--global \
--purpose=PRIVATE_SERVICE_CONNECT \
--addresses=<pscendpointip> \
--network=mynet
pscendpointip=$(gcloud compute addresses list --filter=name:pscglobalip --format="value(address)")
echo $pscendpointip
یک قانون ارسال برای اتصال نقطه پایانی به APIها و سرویسهای گوگل ایجاد کنید.
gcloud compute forwarding-rules create pscendpoint \
--global \
--network=mynet \
--address=pscglobalip \
--target-google-apis-bundle=all-apis
بررسی p.googleapis.com در Cloud DNS
وقتی یک نقطه پایانی ایجاد میکنید، تنظیمات DNS زیر به طور خودکار ایجاد میشوند:
- یک منطقه DNS خصوصی در دایرکتوری سرویس برای p.googleapis.com ایجاد شده است.
- رکوردهای DNS برای برخی از APIها و سرویسهای رایج گوگل که با استفاده از Private Service Connect در دسترس هستند و نامهای DNS پیشفرضی دارند که به googleapis.com ختم میشوند، در p.googleapis.com ایجاد میشوند.
نقاط پایانی سراسری در فهرست خدمات ثبت شدهاند. شما برای دسترسی به فضای ذخیرهسازی ابری از storage-[psc endpoint name].p.googleapis.com استفاده خواهید کرد. برای جزئیات بیشتر، مستندات محصول در اینجا آمده است.
با اجرای دستور زیر بررسی کنید که آیا منطقه p.googleaps.com از قبل ایجاد شده است یا خیر.
gcloud dns managed-zones list
اگر میخواهید از نام DNS پیشفرض، storage.googleapis.com، استفاده کنید، باید یک منطقه خصوصی storage.googleapis.com در Cloud DNS ایجاد کنید و رکورد apex را که به نقطه پایانی PSC آدرس IP دامنه جهانی اشاره میکند، اضافه کنید.
ایجاد نقطه پایانی PSC با محدوده منطقهای برای ذخیرهسازی ابری
شما به یک IP از زیرشبکه VPC نیاز دارید. دستور زیر را اجرا کنید، یک IP از زیرشبکه برای نقطه پایانی PSC اختصاص داده خواهد شد.
gcloud network-connectivity regional-endpoints create psc-regional-endpoint \
--region=$region \
--network=projects/$project_id/global/networks/mynet \
--subnetwork=projects/$project_id/regions/$region/subnetworks/mysubnet \
--target-google-api=storage.us-central1.rep.googleapis.com
آدرس IP نقطه پایانی ایجاد شده از مرحله بالا را دریافت کنید.
regionalip=$(gcloud network-connectivity regional-endpoints describe psc-regional-endpoint --region=$region --format="value(address)")
echo $regionalip
شما برای دسترسی به فضای ذخیرهسازی ابری از storage.us-central1.rep.googleapis.com استفاده خواهید کرد. شما باید یک منطقه خصوصی برای storage.us-central1.rep.googleapis.com و رکورد apex آدرس IP که برای نقطه پایانی منطقهای در Cloud DNS ایجاد کردهاید، ایجاد کنید.
ایجاد یک منطقه خصوصی برای Cloud Storage Regional Endpoint
شما برای دسترسی به نقطه پایانی منطقهای Cloud Storage از storage.[region name].rep.googleapis.com استفاده خواهید کرد.
شما باید یک منطقه خصوصی در Cloud DNS ایجاد کنید و یک رکورد apex اضافه کنید که به آدرس IP نقطه پایانی منطقهای Cloud Storage اشاره میکند.
در دستور زیر، us-central1 منطقه نمونه است. شما باید منطقه را با نام منطقه خود ایجاد کنید.
gcloud dns managed-zones create psc-regional-endpoint-zone \
--description="" \
--dns-name="storage.us-central1.rep.googleapis.com" \
--visibility="private" \
--networks="mynet"
gcloud dns record-sets create storage.us-central1.rep.googleapis.com. \
--rrdatas=$regionalip \
--ttl=300 \
--type=A \
--zone=psc-regional-endpoint-zone
۶. پیکربندی Cloud Run job با نقطه پایانی PSC از Global Scope
کد را دریافت کنید
شما ابتدا یک برنامه Node.js را برای گرفتن اسکرینشات از صفحات وب و ذخیره آنها در Cloud Storage بررسی میکنید. بعداً، یک تصویر کانتینر برای برنامه میسازید و آن را به عنوان یک کار در Cloud Run اجرا میکنید.
از Cloud Shell، دستور زیر را برای کپی کردن کد برنامه از این مخزن اجرا کنید:
git clone https://github.com/GoogleCloudPlatform/jobs-demos.git
به دایرکتوری حاوی برنامه بروید:
cd jobs-demos/screenshot
شما باید این طرح فایل را ببینید:
|
├── داکرفایل
├── فایل README.md
├── اسکرینشات.js
├── فایل package.json
در اینجا توضیح مختصری در مورد هر فایل آمده است:
- فایل screenshot.js شامل کد Node.js برای برنامه است. این برنامه از صفحات وب اسکرینشات میگیرد و آنها را در فضای ذخیرهسازی ابری ذخیره میکند.
- فایل package.json وابستگیهای کتابخانه را تعریف میکند.
- داکرفایل، تصویر کانتینر را تعریف میکند.
کد screenshot.js را باز کنید، شما apiEndpoint را به PSC global endpoint تغییر خواهید داد. کد را جستجو کنید و const storage = new Storage(); را با موارد زیر جایگزین کنید:
const storage = new Storage(
{
apiEndpoint:'https://storage-pscendpoint.p.googleapis.com.',
useAuthWithCustomEndpoint: true
}
);
یک شغل را مستقر کنید
قبل از ایجاد یک کار، باید یک حساب کاربری سرویس ایجاد کنید که برای اجرای کار از آن استفاده خواهید کرد.
gcloud iam service-accounts create screenshot-sa --display-name="Screenshot app service account"
نقش storage.admin را به حساب سرویس اعطا کنید تا بتوان از آن برای ایجاد سطلها و اشیاء استفاده کرد.
gcloud projects add-iam-policy-binding $project_id \
--role roles/storage.admin \
--member serviceAccount:screenshot-sa@$project_id.iam.gserviceaccount.com
به حساب کاربری پیشفرض سرویس محاسباتی، نقشهای Storage Object User، Logs Writer و Artifact Registry Repository Administrator را اعطا کنید.
project_number=$(gcloud projects describe $project_id --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $project_id \
--role roles/storage.objectUser \
--member serviceAccount:$project_number-compute@developer.gserviceaccount.com
gcloud projects add-iam-policy-binding $project_id \
--role roles/logging.logWriter \
--member serviceAccount:$project_number-compute@developer.gserviceaccount.com
gcloud projects add-iam-policy-binding $project_id \
--role roles/artifactregistry.repoAdmin \
--member serviceAccount:$project_number-compute@developer.gserviceaccount.com
شما خروجی مستقیم VPC را برای کارهای Cloud Run فعال خواهید کرد تا تمام ترافیک به یک شبکه VPC ارسال شود.
درون Cloud Shell، موارد زیر را انجام دهید:
gcloud run jobs deploy screenshot-1 \
--source=. \
--args="https://example.com" \
--args="https://cloud.google.com" \
--tasks=2 \
--task-timeout=5m \
--region=$region \
--set-env-vars=BUCKET_NAME=screenshot-$project_id-$RANDOM \
--service-account=screenshot-sa@$project_id.iam.gserviceaccount.com \
--vpc-egress=all-traffic \
--network=mynet \
--subnet=mysubnet
کار را اجرا کنید
درون Cloud Shell، موارد زیر را انجام دهید:
gcloud run jobs execute screenshot-1 --region=$region
وضعیت کار و گزارشها را بررسی کنید. به کنسول Cloud Run بروید و کار را جستجو کنید. روی کار کلیک کنید و تاریخچه گزارش را بررسی کنید. نتیجه اجرای کار مشابه زیر را مشاهده خواهید کرد.

برای مشاهده گزارشهای دقیق اجرای کار، روی «مشاهده گزارش» در محل کار کلیک کنید. گزارشهای کار مشابهی را مانند زیر مشاهده خواهید کرد.

یک سطل جدید ایجاد شده است. میتوانید به کنسول Cloud Storage بروید و سطل جدید ایجاد شده را بررسی کنید. لطفاً توجه داشته باشید که از آنجایی که از Cloud Storage Global Endpoint استفاده میکنید، سطل یک سطل چند منطقهای است. میتوانید تصاویر آپلود شده در سطل را بررسی کنید.
نتیجه آزمایش، Cloud Run با دسترسی خصوصی به Cloud Storage Global Endpoint را نشان میدهد که شما در کار Cloud Run آن را تغییر دادهاید:
apiEndpoint:'https://storage-pscendpoint.p.googleapis.com'
۷. پیکربندی Cloud Run job با نقطه پایانی PSC از محدوده منطقهای
در کد، شما apiEndpoint را به PSC endpoint با دامنه منطقهای تغییر خواهید داد.
کد را جستجو کنید و const storage = new Storage(); را با عبارت زیر جایگزین کنید (ما از us-central1 به عنوان مثال استفاده میکنیم. لطفاً منطقه خود را وارد کنید):
const storage = new Storage(
{
apiEndpoint:'https://storage.us-central1.rep.googleapis.com.',
useAuthWithCustomEndpoint: true
}
);
یک شغل را مستقر کنید
مطمئن شوید که در دایرکتوری حاوی برنامه (jobs-demos/screenshot) هستید.
pwd
شما خروجی مستقیم VPC را برای ارسال تمام ترافیک به شبکه VPC فعال میکنید.
درون Cloud Shell، موارد زیر را انجام دهید:
gcloud run jobs deploy screenshot-2 \
--source=. \
--args="https://example.com" \
--args="https://cloud.google.com" \
--tasks=2 \
--task-timeout=5m \
--region=$region \
--set-env-vars=BUCKET_NAME=screenshot-$PROJECT_ID-$RANDOM \
--service-account=screenshot-sa@$project_id.iam.gserviceaccount.com \
--vpc-egress=all-traffic \
--network=mynet \
--subnet=mysubnet
کار را اجرا کنید
درون Cloud Shell، موارد زیر را انجام دهید:
gcloud run jobs execute screenshot-2 --region=$region
وضعیت کار و گزارشها را بررسی کنید. به کنسول Cloud Run بروید و کار را جستجو کنید. روی کار کلیک کنید و تاریخچه کار را بررسی کنید. نتیجه اجرای کار مشابه زیر را مشاهده خواهید کرد.

برای مشاهده گزارشهای دقیق اجرای کار، روی «مشاهده گزارش» کلیک کنید. گزارشهای کار مشابهی را مانند زیر مشاهده خواهید کرد.

یک سطل جدید ایجاد شده است. میتوانید به کنسول Cloud Storage بروید و سطل جدید ایجاد شده را بررسی کنید. لطفاً توجه داشته باشید که از Cloud Storage Regional Endpoint استفاده میکنید، سطل یک سطل تک منطقهای است. میتوانید تصاویر آپلود شده در سطل را بررسی کنید.
نتیجه آزمایش، Cloud Run با دسترسی خصوصی به Cloud Storage Regional Endpoint را نشان میدهد که شما در کار Cloud Run آن را تغییر دادهاید:
apiEndpoint:'https://storage.us-central1.rep.googleapis.com'
۸. تمیز کردن
شغل پاکسازی فضای ابری
gcloud run jobs delete screenshot-1 \
--region=$region --quiet
gcloud run jobs delete screenshot-2 \
--region=$region --quiet
gcloud iam service-accounts delete screenshot-sa@$project_id.iam.gserviceaccount.com --quiet
پاکسازی نقطه پایانی PSC
gcloud compute forwarding-rules delete pscendpoint \
--global --quiet
gcloud network-connectivity regional-endpoints delete psc-regional-endpoint \
--region=$region --quiet
gcloud compute addresses delete pscglobalip \
--global --quiet
پاکسازی Cloud NAT، Cloud Router و VPCها
gcloud compute routers nats delete $region-nat \
--router=$region-cr \
--region=$region --quiet
gcloud compute routers delete $region-cr \
--region=$region --quiet
gcloud compute networks subnets delete mysubnet \
--region=$region --quiet
gcloud compute networks delete mynet --quiet
۹. تبریک
شما با موفقیت دسترسی خصوصی Cloud Run به Cloud Storage را از طریق Global Endpoint و Regional Endpoint آزمایش کردید.