کتابخانه google-api-python-client در پایتون — معرفی و کاربردها

کتابخانه google-api-python-client ابزار رسمی گوگل برای دسترسی به سرویس‌های مختلف Google از طریق زبان پایتون است. این کتابخانه روی ساختن درخواست‌ها بر پایه مستندات Discovery API گوگل تمرکز دارد و به شما اجازه می‌دهد با کمترین پیچیدگی به سرویس‌هایی مثل Drive، Sheets، Calendar، Gmail و بسیاری دیگر متصل شوید.

ویژگی‌های کلیدی

• دسترسی به بیش از ۲۰۰ API گوگل با استفاده از یک رابط یکنواخت.
• پشتیبانی از احراز هویت OAuth 2.0 و Service Account.
• پشتیبانی از batch requests، resumable uploads و مدیریت صف درخواست‌ها.
• قابلیت تنظیم زمان‌تایم‌اوت، retries و مدیریت خطاها.

نصب و پیش‌نیازها

برای نصب کتابخانه‌ها معمولاً از pip استفاده می‌کنیم:

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

این دستور، کتابخانه کلاینت همراه با ابزارهای احراز هویت را نصب می‌کند تا بتوانید هم با OAuth دسکتاپ/وب و هم با Service Account کار کنید.

روش‌های احراز هویت

دو روش اصلی برای احراز هویت وجود دارد:

• OAuth 2.0 (برای تعاملات کاربر محور) — برای برنامه‌هایی که به اجازه‌ی کاربر نیاز دارند (مثلاً اپیلیکیشن دسکتاپ یا وب).
• Service Account (برای سرور به سرور) — برای اسکریپت‌ها یا سرویس‌های بک‌اند که نیاز به دسترسی بدون حضور کاربر دارند.

نمونه احراز هویت با OAuth (Drive API)

from googleapiclient.discovery import build
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/drive.metadata.readonly']

flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
creds = flow.run_local_server(port=0)
service = build('drive', 'v3', credentials=creds)

results = service.files().list(pageSize=10, fields="files(id, name)").execute()
for f in results.get('files', []):
    print(f['id'], f['name'])

توضیح: این کد با استفاده از فایل credentials.json که از کنسول گوگل دریافت می‌کنید، پنجره مرورگر باز می‌کند تا کاربر اجازه دهد. سپس با متد build یک سرویس Drive ایجاد و ده فایل اول را لیست می‌کند.

نمونه با Service Account

from googleapiclient.discovery import build
from google.oauth2 import service_account

SCOPES = ['https://www.googleapis.com/auth/drive']
SERVICE_ACCOUNT_FILE = 'service-account.json'

creds = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)
# در صورت نیاز به انجام عملیات با امضاء کاربر خاص:
# creds = creds.with_subject('user@example.com')

service = build('drive', 'v3', credentials=creds)
file_list = service.files().list(pageSize=5).execute()
print(file_list.get('files', []))

توضیح: این مثال مناسب سرویس‌های سرور-به-سر است. فایل کلید سرویس (JSON) را از گوگل دریافت و استفاده می‌کنیم. اگر به نمایندگی از یک کاربر دامنه کار می‌کنیم، می‌توانیم با with_subject امضا (delegation) انجام دهیم.

نکات عملی و بهترین شیوه‌ها

• کمترین دسترسی ممکن: فقط scopeهای لازم را درخواست کنید تا امنیت حفظ شود.
• استفاده از فِیلدها (fields): با پارامتر fields فقط فیلدهای مورد نیاز را بخوانید تا مصرف کوتا و زمان پاسخ کاهش یابد.
• مدیریت خطا و Retries: از backoff نمایی و مدیریت خطاهای HttpError استفاده کنید تا در مواجهه با نرخ محدودیت (rate limit) یا خطاهای موقتی هوشمندانه retry کنید.
• ذخیره امن Credentialها: فایل‌های credentials را از کد منبع جدا کنید و از secret managers استفاده کنید.

الگوریتم ساده‌ی retry با exponential backoff

import time
from googleapiclient.errors import HttpError

def execute_with_retries(request, max_retries=5):
    delay = 1
    for attempt in range(max_retries):
        try:
            return request.execute()
        except HttpError as e:
            if e.resp.status in [429, 500, 503]:
                time.sleep(delay)
                delay *= 2
            else:
                raise
    raise Exception('Max retries exceeded')

توضیح: این تابع یک درخواست (مثل service.files().list(...)) می‌گیرد و با استفاده از backoff نمایی در برابر خطاهای موقتی retry می‌کند. این روش باعث می‌شود برنامه شما در برابر نوسان‌های شبکه و محدودیت‌های موقت مقاوم‌تر شود.

کاربردها و مثال‌های واقعی

• همگام‌سازی خودکار فایل‌ها بین سیستم‌های داخلی و Google Drive.
• خواندن و نوشتن داده‌ها در Google Sheets برای داشبوردهای BI یا اتوماسیون گزارش‌گیری.
• ارسال و دریافت ایمیل‌ها با Gmail API برای بات‌های پشتیبانی یا ارشیو اسناد.
• ایجاد رویدادهای تقویم و مدیریت برنامه کاری با Calendar API.

مثال از استفاده بهینه — فقط فیلدهای مورد نیاز (partial response)

results = service.files().list(
    pageSize=20,
    fields="nextPageToken, files(id, name, mimeType)"
).execute()

توضیح: درخواست بالا تنها فیلدهای شناسه، نام و نوع فایل را برمی‌گرداند و باعث کاهش پهنای باند و زمان پردازش می‌شود.

جدول مقایسه‌ی کوتاه — برخی APIهای متداول

خطاهای متداول و رفع آنها

• Invalid Credentials: بررسی کنید توکن منقضی نشده و فایل credentials صحیح است.
• Insufficient Permission: مطمئن شوید scope مناسب را درخواست کرده‌اید و کاربر قبول کرده است.
• Rate Limit Exceeded: از exponential backoff و کاهش فراخوانی‌ها با استفاده از fields و caching استفاده کنید.

جمع‌بندی و نکات نهایی

کتابخانه google-api-python-client یک ابزار قدرتمند و منعطف برای کار با سرویس‌های گوگل در پایتون است. با رعایت اصول امنیتی، استفاده از scopes حداقلی، و مدیریت هوشمندانه‌ی خطاها و retryها می‌توانید سرویس‌های قابل اعتماد و مقیاس‌پذیر بسازید. برای پروژه‌های حساس به مقیاس، توصیه می‌شود کوتا (partial) پاسخ‌ها، batch requests و service accounts را مد نظر قرار دهید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال