گوگل google
احراز هویت حساب سرویس گوگل برای APIهای گوگل.
واردسازی گوگل
نام آرگومانها شناسهی خود کد است و معادل فارسی ندارد؛ گونهها، کلیدواژهها و نام بستهها با معادل فارسی نوشته میشوند.
برنامههای سرور با یک «حساب سرویس» به APIهای گوگل وصل میشوند. پروندهی جیسون حساب را از کنسول گوگل بگیرید، با تجزیه حساب سرویس بخوانید و با توکن دسترسی برای دامنهی لازم توکن بگیرید؛ بعد آن را با سرآیند مجوز در درخواستهای اچ تی تی پی بفرستید. پروندهی حساب سرویس را مثل گذرواژه نگه دارید.
این بسته یک کار انجام میدهد: یک JWT را با کلید RSA حساب (RS256) امضا میکند، آن را در نقطهی توکن گوگل با یک توکن دسترسی OAuth عوض میکند و آن توکن را برای استفادهی دوباره نگه میدارد. خود فراخوانی APIها درخواستهای HTTP معمولیاند که خودتان مینویسید. برای اعلان وب به مرورگرها بدون فایربیس، webpush را ببینید.
چند نکته که معمولاً غافلگیر میکند:
- فقط کلید حساب سرویس پشتیبانی میشود. ورود خود کاربر با حساب گوگلش (صفحهی رضایت OAuth) و سرور فرادادهای که ماشینهای Google Cloud دارند، پشتیبانی نمیشوند.
- وقتی
توکن دسترسیشکست بخورد،okنادرست میشود و پیامی در کار نیست. به این ترتیب بررسی کنید:okخود حساب، ساعت ماشین (ساعتی که چند دقیقه جلو یا عقب باشد امضا را نزد گوگل نامعتبر میکند)، شبکه، و اینکه API برای پروژه فعال شده باشد. - هر توکن برای هر حساب و دامنه ۵۹ دقیقه نگه داشته میشود و همهی نخها در آن شریکاند. پس از تغییر نقشهای حساب،
فراموش کردن توکنرا صدا بزنید تا فراخوان بعدی توکن تازه بگیرد.
بار کردن امن حساب سرویس
کلید JSON را از کنسول Google Cloud بگیرید (IAM، Service accounts، Keys) و بیرون از پوشهی کد نگهش دارید؛ جای رایج برای نشان دادن آن متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS است که با دریافت با پیش فرض از محیط خوانده میشود. تجزیه حساب سرویس هیچوقت با سروصدا شکست نمیخورد: وقتی متن خالی است یا client_email یا private_key را ندارد، حسابی برمیگرداند که ok آن نادرست است. این را یک بار هنگام شروع بررسی کنید و با پیامی روشن بایستید، تا استقرار خراب همان اول شکست بخورد، نه هنگام نخستین اعلان.
واردسازی گوگل
واردسازی ورودی خروجی
تابع بارگذاری(مسیر: رشته): گوگل.حساب سرویس:
متن := ورودی خروجی.خواندن پرونده(مسیر)
اگر متن == "":
سرچاپ "خواندن"، مسیر، "ممکن نیست"
برگشت گوگل.حساب سرویس {}
پایان
حساب := گوگل.تجزیه حساب سرویس(متن)
اگر وارونه حساب.موفق:
سرچاپ مسیر، "پروندهی حساب سرویس نیست: client_email یا private_key ندارد"
پایان
برگشت حساب
پایان
تابع ریشه:
ورودی خروجی.نوشتن پرونده("good.json"، `{"type":"service_account","project_id":"shop-prod","client_email":"push@shop-prod.iam.gserviceaccount.com","private_key":"-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"}`)
ورودی خروجی.نوشتن پرونده("broken.json"، `{"type":"service_account","project_id":"shop-prod"}`)
هر م در ["good.json"، "broken.json"، "missing.json"]:
حساب := بارگذاری(م)
اگر حساب.موفق:
سرچاپ "پروژهی"، حساب.شناسه پروژه، "با حساب"، حساب.ایمیل حساب
سرچاپ "کلید بار شد:"، حساب.کلید خصوصی.طول() > ۰
پایان
پایان
پایانبرنامه پروژه و ایمیل حساب را چاپ میکند که ثبتشان در گزارش بیخطر است، اما دربارهی کلید فقط میگوید بار شد یا نه. هیچوقت private_key را چاپ یا در گزارش ثبت نکنید و پرونده را در مخزن کد نگذارید: هر کس آن را داشته باشد میتواند به نام سرویس شما کار کند.
فرستادن اعلان با Firebase
Firebase Cloud Messaging برای هر پیام یک درخواست HTTP میگیرد. برای دامنه اف سی ام توکن بگیرید، آن را در سرآیند Authorization بگذارید و پیام را به /v1/projects/PROJECT/messages:send بفرستید. توکن دسترسی توکن را نگه میدارد و تا کمی پیش از انقضا دوباره به کار میبرد؛ پس صدا زدنش پیش از هر پیام، بعد از بار اول هزینهای ندارد.
واردسازی گوگل
واردسازی ورودی خروجی
واردسازی شبکه.اچ تی تی پی
تابع فرستادن اعلان(حساب: گوگل.حساب سرویس، توکن دستگاه: رشته، عنوان: رشته، متن: رشته): منطقی:
ناپایا گرفت := نادرست
توکن := گوگل.توکن دسترسی(حساب، گوگل.دامنه اف سی ام، گرفت)
اگر وارونه گرفت:
سرچاپ "توکن دسترسی گرفته نشد"
برگشت نادرست
پایان
نشانی := "https://fcm.googleapis.com/v1/projects/" + حساب.شناسه پروژه + "/messages:send"
پیام := ```
{"message": {"token": "${{ توکن دستگاه }}", "notification": {"title": "${{ عنوان }}", "body": "${{ متن }}"}}}
```
ناپایا سرآیندها := اچ تی تی پی.سرصفحه جدید()
سرآیندها.درج("Authorization"، گوگل.سرآیند مجوز(توکن))
سرآیندها.درج("Content-Type"، "application/json")
پ := اچ تی تی پی.ارسال با(نشانی، پیام، سرآیندها)
اگر اچ تی تی پی.وضعیت(پ) != ۲۰۰:
سرچاپ "پاسخ FCM:"، اچ تی تی پی.وضعیت(پ)، اچ تی تی پی.بدنه(پ)
برگشت نادرست
پایان
سرچاپ "فرستاده شد:"، اچ تی تی پی.بدنه(پ)
برگشت درست
پایان
تابع ریشه:
حساب := گوگل.تجزیه حساب سرویس(ورودی خروجی.خواندن پرونده("service-account.json"))
اگر وارونه حساب.موفق:
سرچاپ "service-account.json پیدا نشد یا نامعتبر است"
برگشت ۱
پایان
فرستادن اعلان(حساب، "DEVICE_REGISTRATION_TOKEN"، "سفارش فرستاده شد"، "بستهی شما در راه است")
فرستادن اعلان(حساب، "DEVICE_REGISTRATION_TOKEN"، "تحویل شد"، "بستهی شما رسید")
برگشت ۰
پایاناین نمونه به یک حساب سرویس واقعی با API فعال Firebase Cloud Messaging و یک توکن ثبت دستگاه از برنامهی شما نیاز دارد، پس اینجا فقط کامپایل میشود. کلید را با نام service-account.json ذخیره کنید و DEVICE_REGISTRATION_TOKEN را عوض کنید. در صورت موفقیت، بدنه نام پیام را دارد، {"name": "projects/.../messages/..."}؛ خطایی که در بدنهاش UNREGISTERED آمده یعنی برنامه از دستگاه پاک شده و باید آن توکن را حذف کنید. عنوان و متن همانطور که هستند در JSON گذاشته میشوند؛ اگر ممکن است گیومه داشته باشند، پیام را با encoding.json بسازید.
بارگذاری پرونده در Cloud Storage
یک بارگذاری ساده یعنی یک POST از بایتهای پرونده به نشانی بارگذاری، با نام شیء در رشتهی پرسوجو و نوع محتوا در یک سرآیند. توکن از دامنه ذخیرهسازی میآید. نام شیء ممکن است / داشته باشد، پس پیش از گذاشتن در نشانی آن را با کدگذاری بخش مسیر از نشانی وب کدگذاری کنید.
واردسازی گوگل
واردسازی ورودی خروجی
واردسازی شبکه.اچ تی تی پی
واردسازی کدگذاری.نشانی وب
تابع بارگذاری(حساب: گوگل.حساب سرویس، سطل: رشته، نام: رشته، محتوا: رشته، نوع محتوا: رشته): منطقی:
ناپایا گرفت := نادرست
توکن := گوگل.توکن دسترسی(حساب، گوگل.دامنه ذخیرهسازی، گرفت)
اگر وارونه گرفت:
برگشت نادرست
پایان
مقصد := "https://storage.googleapis.com/upload/storage/v1/b/" + سطل + "/o?uploadType=media&name=" + نشانی وب.کدگذاری بخش مسیر(نام)
ناپایا سرآیندها := اچ تی تی پی.سرصفحه جدید()
سرآیندها.درج("Authorization"، گوگل.سرآیند مجوز(توکن))
سرآیندها.درج("Content-Type"، نوع محتوا)
پ := اچ تی تی پی.ارسال با(مقصد، محتوا، سرآیندها)
سرچاپ نام، "->"، اچ تی تی پی.وضعیت(پ)
برگشت اچ تی تی پی.وضعیت(پ) == ۲۰۰
پایان
تابع ریشه:
حساب := گوگل.تجزیه حساب سرویس(ورودی خروجی.خواندن پرونده("service-account.json"))
اگر وارونه حساب.موفق:
سرچاپ "service-account.json پیدا نشد یا نامعتبر است"
برگشت ۱
پایان
بارگذاری(حساب، "my-bucket"، "reports/2026-10.csv"، "day,sales\n1,120\n2,95\n"، "text/csv")
بارگذاری(حساب، "my-bucket"، "notes/salam.txt"، "سلام"، "text/plain; charset=utf-8")
گوگل.فراموش کردن توکن(حساب)
برگشت ۰
پایانبهجای my-bucket سطلی بگذارید که حساب سرویس بتواند در آن بنویسد (نقش Storage Object Creator کافی است). وضعیت ۲۰۰ یعنی شیء ذخیره شد؛ ۴۰۳ یعنی حساب روی آن سطل اجازه ندارد. فراموش کردن توکن توکن نگهداشتهشده را دور میریزد، که پس از عوض کردن کلید یا نقشهای حساب به کار میآید.
| سرویس | دامنه |
|---|---|
| Firebase Cloud Messaging | دامنه اف سی ام |
| Cloud Storage | دامنه ذخیرهسازی |
| بیشتر APIهای دیگر Google Cloud | دامنه ابر، یا رشتهی دامنهی خود آن API |
گونهها
حساب سرویس ServiceAccount
ساختار حساب سرویس| نام | انگلیسی | گونه | توضیح |
|---|---|---|---|
| ایمیل حساب | client_email | رشته = "" | ایمیل حساب. |
| کلید خصوصی | private_key | رشته = "" | کلید خصوصی PEM. |
| نشانی توکن | token_uri | رشته = "https://oauth2.googleapis.com/token" | نشانی گرفتن توکن. |
| شناسه پروژه | project_id | رشته = "" | شناسهی پروژه. |
| موفق | ok | منطقی = نادرست | درست خوانده شد. |
واردسازی گوگل
تابع ریشه:
سند := `{"type":"service_account","project_id":"salam-demo","client_email":"bot@salam-demo.iam.gserviceaccount.com","private_key":"(کلید خصوصی اینجا)"}`
ح := گوگل.تجزیه حساب سرویس(سند)
سرچاپ ح.موفق، ح.شناسه پروژه، ح.ایمیل حساب
سرچاپ ح.نشانی توکن
سرچاپ ح.کلید خصوصی.طول() > ۰
سرچاپ گوگل.تجزیه حساب سرویس(`{"project_id":"x"}`).موفق
سرچاپ گوگل.سرآیند مجوز("ya29.abc")
سرچاپ گوگل.دامنه اف سی ام
سرچاپ گوگل.دامنه ذخیرهسازی
سرچاپ گوگل.دامنه ابر
پایانپایاها و متغیرها
دامنه اف سی ام SCOPE_FCM
پایا دامنه اف سی ام: رشته = "https://www.googleapis.com/auth/firebase.messaging"نمونهی این مورد همراه با موارد بالاتر آمده است: google-Account.salam
دامنه ذخیرهسازی SCOPE_STORAGE
پایا دامنه ذخیرهسازی: رشته = "https://www.googleapis.com/auth/devstorage.read_write"نمونهی این مورد همراه با موارد بالاتر آمده است: google-Account.salam
دامنه ابر SCOPE_CLOUD
پایا دامنه ابر: رشته = "https://www.googleapis.com/auth/cloud-platform"نمونهی این مورد همراه با موارد بالاتر آمده است: google-Account.salam
تابعها
تجزیه حساب سرویس ParseServiceAccount
تابع تجزیه حساب سرویس(document: رشته): حساب سرویسclient_email یا private_key نباشد، ok نتیجه نادرست است. اگر پرونده token_uri نداشته باشد، مقدار پیشفرض میماند.نمونهی این مورد همراه با موارد بالاتر آمده است: google-Account.salam
توکن دسترسی AccessToken
تابع توکن دسترسی(sa: حساب سرویس، scope: رشته، ok &: منطقی): رشتهok را نادرست میکند و دلیلی نمیگوید.واردسازی گوگل
واردسازی ورودی خروجی
واردسازی شبکه.اچ تی تی پی
تابع ریشه:
ح := گوگل.تجزیه حساب سرویس(ورودی خروجی.خواندن پرونده("service-account.json"))
اگر وارونه ح.موفق:
سرچاپ "پروندهی حساب سرویس درست نیست"
برگشت
پایان
ناپایا سالم := نادرست
توکن := گوگل.توکن دسترسی(ح، گوگل.دامنه ذخیرهسازی، سالم)
اگر وارونه سالم:
سرچاپ "توکن گرفته نشد"
برگشت
پایان
ناپایا سر := اچ تی تی پی.سرصفحه جدید()
سر.درج("Authorization"، گوگل.سرآیند مجوز(توکن))
پ := اچ تی تی پی.دریافت با("https://storage.googleapis.com/storage/v1/b?project=" + ح.شناسه پروژه، سر)
سرچاپ اچ تی تی پی.وضعیت(پ)
گوگل.فراموش کردن توکن(ح)
پایانفراموش کردن توکن Forget
تابع فراموش کردن توکن(sa: حساب سرویس)نمونهی این مورد همراه با موارد بالاتر آمده است: google-Token.salam
سرآیند مجوز Authorization
تابع سرآیند مجوز(token: رشته): رشتهAuthorization با توکن.نمونهی این مورد همراه با موارد بالاتر آمده است: google-Account.salam