کتابخانه‌ی استاندارد · وب و سرویس‌ها

گوگل 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 آن نادرست است. این را یک بار هنگام شروع بررسی کنید و با پیامی روشن بایستید، تا استقرار خراب همان اول شکست بخورد، نه هنگام نخستین اعلان.

google-guide-load.salam
واردسازی گوگل
واردسازی ورودی خروجی

تابع بارگذاری(مسیر: رشته): گوگل.حساب سرویس:
    متن := ورودی خروجی.خواندن پرونده(مسیر)
    اگر متن == "":
        سرچاپ "خواندن"، مسیر، "ممکن نیست"
        برگشت گوگل.حساب سرویس {}
    پایان
    حساب := گوگل.تجزیه حساب سرویس(متن)
    اگر وارونه حساب.موفق:
        سرچاپ مسیر، "پرونده‌ی حساب سرویس نیست: 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"]:
        حساب := بارگذاری(م)
        اگر حساب.موفق:
            سرچاپ "پروژه‌ی"، حساب.شناسه پروژه، "با حساب"، حساب.ایمیل حساب
            سرچاپ "کلید بار شد:"، حساب.کلید خصوصی.طول() > ۰
        پایان
    پایان
پایان
خروجیپروژه‌ی shop-prod با حساب push@shop-prod.iam.gserviceaccount.com کلید بار شد: true broken.json پرونده‌ی حساب سرویس نیست: client_email یا private_key ندارد خواندن missing.json ممکن نیست

برنامه پروژه و ایمیل حساب را چاپ می‌کند که ثبتشان در گزارش بی‌خطر است، اما درباره‌ی کلید فقط می‌گوید بار شد یا نه. هیچ‌وقت private_key را چاپ یا در گزارش ثبت نکنید و پرونده را در مخزن کد نگذارید: هر کس آن را داشته باشد می‌تواند به نام سرویس شما کار کند.

فرستادن اعلان با Firebase

Firebase Cloud Messaging برای هر پیام یک درخواست HTTP می‌گیرد. برای دامنه اف سی ام توکن بگیرید، آن را در سرآیند Authorization بگذارید و پیام را به /v1/projects/PROJECT/messages:send بفرستید. توکن دسترسی توکن را نگه می‌دارد و تا کمی پیش از انقضا دوباره به کار می‌برد؛ پس صدا زدنش پیش از هر پیام، بعد از بار اول هزینه‌ای ندارد.

google-guide-fcm.salam
واردسازی گوگل
واردسازی ورودی خروجی
واردسازی شبکه.اچ تی تی پی

تابع فرستادن اعلان(حساب: گوگل.حساب سرویس، توکن دستگاه: رشته، عنوان: رشته، متن: رشته): منطقی:
    ناپایا گرفت := نادرست
    توکن := گوگل.توکن دسترسی(حساب، گوگل.دامنه اف سی ام، گرفت)
    اگر وارونه گرفت:
        سرچاپ "توکن دسترسی گرفته نشد"
        برگشت نادرست
    پایان
    نشانی := "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 از بایت‌های پرونده به نشانی بارگذاری، با نام شیء در رشته‌ی پرس‌وجو و نوع محتوا در یک سرآیند. توکن از دامنه ذخیره‌سازی می‌آید. نام شیء ممکن است / داشته باشد، پس پیش از گذاشتن در نشانی آن را با کدگذاری بخش مسیر از نشانی وب کدگذاری کنید.

google-guide-storage.salam
واردسازی گوگل
واردسازی ورودی خروجی
واردسازی شبکه.اچ تی تی پی
واردسازی کدگذاری.نشانی وب

تابع بارگذاری(حساب: گوگل.حساب سرویس، سطل: رشته، نام: رشته، محتوا: رشته، نوع محتوا: رشته): منطقی:
    ناپایا گرفت := نادرست
    توکن := گوگل.توکن دسترسی(حساب، گوگل.دامنه ذخیره‌سازی، گرفت)
    اگر وارونه گرفت:
        برگشت نادرست
    پایان
    مقصد := "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منطقی = نادرستدرست خوانده شد.
google-Account.salam
واردسازی گوگل

تابع ریشه:
    سند := `{"type":"service_account","project_id":"salam-demo","client_email":"bot@salam-demo.iam.gserviceaccount.com","private_key":"(کلید خصوصی این‌جا)"}`
    ح := گوگل.تجزیه حساب سرویس(سند)
    سرچاپ ح.موفق، ح.شناسه پروژه، ح.ایمیل حساب
    سرچاپ ح.نشانی توکن
    سرچاپ ح.کلید خصوصی.طول() > ۰
    سرچاپ گوگل.تجزیه حساب سرویس(`{"project_id":"x"}`).موفق
    سرچاپ گوگل.سرآیند مجوز("ya29.abc")
    سرچاپ گوگل.دامنه اف سی ام
    سرچاپ گوگل.دامنه ذخیره‌سازی
    سرچاپ گوگل.دامنه ابر
پایان
خروجیtrue salam-demo bot@salam-demo.iam.gserviceaccount.com https://oauth2.googleapis.com/token true false Bearer ya29.abc https://www.googleapis.com/auth/firebase.messaging https://www.googleapis.com/auth/devstorage.read_write https://www.googleapis.com/auth/cloud-platform

پایاها و متغیرها

دامنه اف سی ام SCOPE_FCM

پایا دامنه اف سی ام: رشته = "https://www.googleapis.com/auth/firebase.messaging"
دامنه‌ی دسترسی برای فرستادن اعلان با Firebase Cloud Messaging.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: google-Account.salam

دامنه ذخیره‌سازی SCOPE_STORAGE

پایا دامنه ذخیره‌سازی: رشته = "https://www.googleapis.com/auth/devstorage.read_write"
دامنه‌ی خواندن و نوشتن در Cloud Storage.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: google-Account.salam

دامنه ابر SCOPE_CLOUD

پایا دامنه ابر: رشته = "https://www.googleapis.com/auth/cloud-platform"
دامنه‌ی کامل Google Cloud.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: google-Account.salam

تابع‌ها

تجزیه حساب سرویس ParseServiceAccount

تابع تجزیه حساب سرویس(document: رشته): حساب سرویس
متن پرونده‌ی جیسون حساب سرویس را می‌خواند. هیچ‌وقت با سروصدا شکست نمی‌خورد: اگر client_email یا private_key نباشد، ok نتیجه نادرست است. اگر پرونده token_uri نداشته باشد، مقدار پیش‌فرض می‌ماند.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: google-Account.salam

توکن دسترسی AccessToken

تابع توکن دسترسی(sa: حساب سرویس، scope: رشته، ok &: منطقی): رشته
توکن دسترسی OAuth برای دامنه‌ی داده‌شده می‌گیرد. چند دامنه را می‌شود با فاصله از هم داد. توکن برای هر حساب و دامنه نگه داشته می‌شود و ۵۹ دقیقه دوباره به کار می‌رود؛ پس پیش از هر درخواست صدایش بزنید. اگر شکست بخورد، رشته‌ی تهی برمی‌گرداند، ok را نادرست می‌کند و دلیلی نمی‌گوید.
google-Token.salam
واردسازی گوگل
واردسازی ورودی خروجی
واردسازی شبکه.اچ تی تی پی

تابع ریشه:
    ح := گوگل.تجزیه حساب سرویس(ورودی خروجی.خواندن پرونده("service-account.json"))
    اگر وارونه ح.موفق:
        سرچاپ "پرونده‌ی حساب سرویس درست نیست"
        برگشت
    پایان
    ناپایا سالم := نادرست
    توکن := گوگل.توکن دسترسی(ح، گوگل.دامنه ذخیره‌سازی، سالم)
    اگر وارونه سالم:
        سرچاپ "توکن گرفته نشد"
        برگشت
    پایان
    ناپایا سر := اچ تی تی پی.سرصفحه جدید()
    سر.درج("Authorization"، گوگل.سرآیند مجوز(توکن))
    پ := اچ تی تی پی.دریافت با("https://storage.googleapis.com/storage/v1/b?project=" + ح.شناسه پروژه، سر)
    سرچاپ اچ تی تی پی.وضعیت(پ)
    گوگل.فراموش کردن توکن(ح)
پایان

فراموش کردن توکن Forget

تابع فراموش کردن توکن(sa: حساب سرویس)
توکن نگه‌داشته‌ی حساب را دور می‌اندازد تا دفعه‌ی بعد تازه گرفته شود.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: google-Token.salam

سرآیند مجوز Authorization

تابع سرآیند مجوز(token: رشته): رشته
مقدار سرآیند Authorization با توکن.

نمونه‌ی این مورد همراه با موارد بالاتر آمده است: google-Account.salam