بدء استخدام Python بسرعة

يمكنك إنشاء تطبيق سطر أوامر بلغة Python يرسل طلبات إلى Postmaster Tools API.

توضّح أدلة التشغيل السريع كيفية إعداد تطبيق وتشغيله لاستدعاء Google Workspace API. يستخدم دليل التشغيل السريع هذا طريقة مصادقة مبسطة مناسبة لبيئة الاختبار. بالنسبة إلى بيئة الإنتاج، ننصحك بالتعرّف على المصادقة والتفويض قبل اختيار بيانات الاعتماد المناسبة لتطبيقك.

يستخدم دليل التشغيل السريع هذا مكتبات برامج Google Workspace API التي ننصح بها للتعامل مع بعض تفاصيل عملية المصادقة والتفويض.

الأهداف

إعداد البيئة
تثبيت مكتبة البرامج
إعداد النموذج
تشغيل النموذج

المتطلبات الأساسية

لتشغيل دليل التشغيل السريع هذا، يجب استيفاء المتطلبات الأساسية التالية:

‫Python 3.10.7 أو إصدار أحدث
أداة إدارة حزم pip
مشروع على Google Cloud.

حساب على Google مفعَّل فيه Gmail

إعداد البيئة

لإكمال دليل التشغيل السريع هذا، عليك إعداد البيئة.

تفعيل واجهة برمجة التطبيقات

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على Google Cloud.

في Google Cloud Console، فعِّل Postmaster Tools API.

تفعيل واجهة برمجة التطبيقات

إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

إذا كنت تستخدم مشروعًا جديدًا على السحابة الإلكترونية من Google لإكمال دليل التشغيل السريع هذا، عليك إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth. إذا سبق لك إكمال هذه الخطوة لمشروعك على السحابة الإلكترونية، فانتقل إلى القسم التالي.

في Google API Console، انتقِل إلى "القائمة" > منصة Google للمصادقة > العلامة التجارية.
الانتقال إلى العلامة التجارية
إذا سبق لك إعداد منصة Google للمصادقة، يمكنك إعداد إعدادات شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth التالية في العلامة التجارية والجمهور والوصول إلى البيانات. إذا ظهرت لك رسالة تشير إلى لم يتم إعداد منصة Google للمصادقة بعد، انقر على البدء:

ضمن معلومات التطبيق، في اسم التطبيق، أدخِل اسمًا للتطبيق.
في البريد الإلكتروني لدعم المستخدمين، اختَر عنوان بريد إلكتروني للدعم يمكن للمستخدمين التواصل معك من خلاله إذا كانت لديهم أسئلة حول موافقتهم.
انقر على التالي.
ضمن الجمهور، اختَر داخلي.
انقر على التالي.
ضمن معلومات الاتصال، أدخِل عنوان بريد إلكتروني يمكنك تلقّي إشعارات من خلاله بشأن أي تغييرات تطرأ على مشروعك.
انقر على التالي.
ضمن إنهاء، راجِع سياسة بيانات المستخدمين في خدمات Google API، وإذا كنت موافقًا عليها، ضَع علامة في المربّع أوافق على سياسة بيانات المستخدمين في خدمات Google API.
انقر على متابعة.
انقر على إنشاء.

يمكنك في الوقت الحالي تخطّي إضافة النطاقات. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسسة Google Workspace، عليك تغيير نوع المستخدم إلى خارجي. بعد ذلك، أضِف نطاقات التفويض التي يتطلبها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على دليل إعداد موافقة OAuth الكامل .

السماح ببيانات اعتماد لتطبيق على الكمبيوتر

لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر لبروتوكول OAuth 2.0. يُستخدم معرّف العميل لتعريف تطبيق واحد لخوادم OAuth من Google. إذا كان تطبيقك يعمل على منصات متعددة، عليك إنشاء معرّف عميل منفصل لكل منصة.

في Google API Console، انتقِل إلى "القائمة" > منصة Google للمصادقة > العملاء.
الانتقال إلى العملاء
انقر على إنشاء عميل.
انقر على نوع التطبيق > تطبيق على الكمبيوتر.
في حقل الاسم ، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في Google API Console.
انقر على إنشاء.
تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن "معرّفات عملاء OAuth 2.0".
احفظ ملف JSON الذي تم تنزيله باسم credentials.json، وانقِل الملف إلى دليل العمل.

تثبيت مكتبة برامج Google

ثبِّت مكتبة برامج Google لـ Python:

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

إعداد النموذج

في دليل العمل، أنشِئ ملفًا باسم quickstart.py.

أدرِج الرمز البرمجي التالي في quickstart.py:

from __future__ import print_function
import pickle
import os.path
from googleapiclient.discovery import build
from google_auth_oauthlib.flow import InstalledAppFlow
from google.auth.transport.requests import Request
from googleapiclient import errors

# If modifying these scopes, delete the file token.pickle.

SCOPES = ['https://www.googleapis.com/auth/postmaster.traffic.readonly']

def main():
    """Shows basic usage of the PostmasterTools v2 API.
    Prints the visible domains on user's domain dashboard in https://postmaster.google.com/managedomains.
    """
    creds = None
    # The file token.pickle stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.pickle'):
        with open('token.pickle', 'rb') as token:
            creds = pickle.load(token)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open('token.pickle', 'wb') as token:
            pickle.dump(creds, token)

    service = build('gmailpostmastertools', 'v2', credentials=creds)

    response = service.domains().list().execute()
    domains = response.get('domains')
    if not domains:
        print('No domains found.')
    else:
        print('Domains:')
        for domain in domains:
            print(domain)
            print('Querying stats for %s' % domain['name'])
            try:
                stats = service.domains().domainStats().query(
                    parent=domain['name'],
                    startDate={'year': 2024, 'month': 1, 'day': 1},
                    endDate={'year': 2024, 'month': 1, 'day': 7}).execute()
                print(stats)
            except errors.HttpError as err:
                print('An error occurred during stats query: %s' % err)

if __name__ == '__main__':
  main()

تشغيل النموذج

في دليل العمل، أنشِئ النموذج وشغِّله:
```
python3 quickstart.py
```

في المرة الأولى التي تشغِّل فيها النموذج، سيُطلب منك السماح بالوصول:
1. إذا لم يسبق لك تسجيل الدخول إلى حساب Google، سجِّل الدخول عندما يُطلب منك ذلك. إذا كنت مسجِّلاً الدخول إلى حسابات متعددة، اختَر حسابًا واحدًا لاستخدامه في التفويض.
2. انقر على حسنًا.
يتم تشغيل تطبيق Python ويستدعي Postmaster Tools API.

يتم تخزين معلومات التفويض في نظام الملفات، لذا لن يُطلب منك منح التفويض في المرة التالية التي تشغِّل فيها نموذج الرمز البرمجي.

الخطوات التالية

تجربة واجهات برمجة التطبيقات في Google Workspace في مستكشف واجهات برمجة التطبيقات

بدء استخدام Python بسرعة تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.