۱. استفاده از APIهای Google Workspace
این آزمایشگاه کد، شما را با نحوه استفاده از APIهای RESTful مبتنی بر HTTP در Google Workspace (که قبلاً G Suite نام داشت) آشنا میکند. این مثال برای اختصار و در دسترس بودن، با زبان پایتون انجام خواهد شد، اما میتوانید از زبان توسعه مورد علاقه خود نیز استفاده کنید. شما با مباحث مقدماتی مانند نحوه استفاده از کنسول توسعهدهندگان برای ایجاد/مدیریت پروژهها، دریافت اعتبارنامههای مجوز و نصب کتابخانههای کلاینت API آشنا خواهید شد. با رعایت تشریفات، برنامهای خواهید نوشت که ۱۰۰ فایل و پوشه اول در Google Drive شما را با استفاده از API آن نمایش میدهد.
آنچه یاد خواهید گرفت
- با استفاده از کنسول توسعهدهندگان گوگل/کلود، یک پروژه ایجاد کنید
- دریافت و استفاده از اعتبارنامههای برنامه OAuth2 در برنامه شما
- آشنایی با استفاده از کتابخانههای کلاینت APIهای گوگل
- نوشتن برنامهها با استفاده از APIهای گوگل و گوگل ورکاسپیس
- اطلاعات فایل و پوشه را با API گوگل درایو دریافت کنید
آنچه نیاز دارید
- دسترسی به اینترنت و مرورگر وب
- یک حساب گوگل (حسابهای کاربری گوگل ورکاسپیس ممکن است نیاز به تأیید مدیر داشته باشند)
- آشنایی با سیستمهای سازگار با POSIX مانند لینوکس و مک او اس ایکس
- امکان ایجاد فایلهای منبع با استفاده از ویرایشگر کد یا دستورات پوسته.
- مهارتهای پایه در پایتون (۲ یا ۳)، اما میتوانید از هر زبان پشتیبانیشدهای استفاده کنید
- برخی از فایلها و/یا پوشهها در گوگل درایو شما
۲. نظرسنجی
چگونه از این آموزش codelab استفاده خواهید کرد؟
تجربه خود را با ابزارها و APIهای توسعهدهندگان Google Workspace چگونه ارزیابی میکنید؟
۳. مرور کلی
در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه:
- کتابخانه کلاینت APIهای گوگل برای پایتون را دانلود کنید
- یک پروژه جدید در کنسول توسعهدهندگان گوگل/کلود ایجاد کنید
- مدارک لازم برای برنامه خود را دریافت کنید
- از این اعتبارنامهها برای دسترسی به API گوگل درایو استفاده کنید
اگر ترجیح میدهید از پایتون استفاده نکنید، میتوانید codelab را در ابزار توسعه مورد علاقه خود پیادهسازی کنید (کتابخانههای کلاینت زبانهای پشتیبانیشده در اینجا موجود است) و به سادگی به مثالهای پایتون به عنوان شبهکد (قابل اجرا) اشاره کنید.
۴. تأیید محیط پایتون
این آزمایشگاه کد شما را ملزم به استفاده از زبان پایتون میکند (اگرچه بسیاری از زبانها توسط کتابخانههای کلاینت API گوگل پشتیبانی میشوند ، بنابراین میتوانید چیزی معادل آن را در ابزار توسعه مورد علاقه خود بسازید و به سادگی از پایتون به عنوان شبه کد استفاده کنید). به طور خاص، این آزمایشگاه کد از پایتون ۲ و ۳ پشتیبانی میکند، اما توصیه میکنیم در اسرع وقت به نسخه ۳.x مهاجرت کنید.
Cloud Shell یک ابزار کاربردی است که مستقیماً از طریق Cloud Console در دسترس کاربران قرار دارد و نیازی به محیط توسعه محلی ندارد، بنابراین این آموزش را میتوان به طور کامل در فضای ابری با یک مرورگر وب انجام داد. Cloud Shell به ویژه در صورتی که در حال توسعه هستید یا قصد دارید به توسعه با محصولات و APIهای GCP ادامه دهید، مفید است. به طور خاصتر برای این آزمایشگاه کد، Cloud Shell از قبل هر دو نسخه پایتون را نصب کرده است.
Cloud Shell همچنین IPython را نصب کرده است... این یک مفسر پایتون تعاملی سطح بالاتر است که ما آن را توصیه میکنیم، به خصوص اگر عضوی از جامعه علوم داده یا یادگیری ماشین هستید. اگر عضوی از این جامعه هستید، IPython مفسر پیشفرض برای Jupyter Notebooks و همچنین Colab ، Jupyter Notebooks میزبانی شده توسط Google Research است.
IPython ابتدا از مفسر پایتون ۳ استفاده میکند، اما اگر پایتون ۳.x در دسترس نباشد، به پایتون ۲ برمیگردد. IPython از طریق Cloud Shell قابل دسترسی است، اما میتوان آن را در یک محیط توسعه محلی نیز نصب کرد. با فشردن کلیدهای ^D (Ctrl-d) از آن خارج شوید و پیشنهاد خروج را بپذیرید. خروجی مثال شروع ipython به این شکل خواهد بود:
$ ipython Python 3.7.3 (default, Mar 4 2020, 23:11:43) Type 'copyright', 'credits' or 'license' for more information IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help. In [1]:
اگر IPython مورد نظر شما نیست، استفاده از یک مفسر تعاملی استاندارد پایتون (یا Cloud Shell یا محیط توسعه محلی شما) کاملاً قابل قبول است (همچنین با ^D خارج شوید):
$ python Python 2.7.13 (default, Sep 26 2018, 18:42:22) [GCC 6.3.0 20170516] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> $ python3 Python 3.7.3 (default, Mar 10 2020, 02:33:39) [GCC 6.3.0 20170516] on linux Type "help", "copyright", "credits" or "license" for more information. >>>
کدلب همچنین فرض میکند که شما ابزار نصب pip (مدیر بسته پایتون و حلکننده وابستگی) را دارید. این ابزار همراه با نسخههای ۲.۷.۹+ یا ۳.۴+ ارائه میشود. اگر نسخه پایتون قدیمیتری دارید، برای دستورالعملهای نصب به این راهنما مراجعه کنید. بسته به مجوزهای شما، ممکن است نیاز به دسترسی sudo یا superuser داشته باشید، اما معمولاً اینطور نیست. همچنین میتوانید به طور صریح pip2 یا pip3 برای اجرای pip برای نسخههای خاص پایتون استفاده کنید.
بقیهی کدها فرض میکنند که شما از پایتون ۳ استفاده میکنید - اگر دستورالعملهای پایتون ۲ تفاوت قابل توجهی با ۳.x داشته باشند، برای آنها دستورالعملهای خاصی ارائه خواهد شد.
* ایجاد و استفاده از محیطهای مجازی
این بخش اختیاری است و فقط برای کسانی که باید از یک محیط مجازی برای این آزمایشگاه کد استفاده کنند (طبق نوار کناری هشدار بالا) واقعاً ضروری است. اگر فقط پایتون ۳ را روی رایانه خود دارید، میتوانید به سادگی این دستور را برای ایجاد یک محیط مجازی به نام my_env صادر کنید (در صورت تمایل میتوانید نام دیگری انتخاب کنید):
virtualenv my_env
با این حال، اگر هر دو نسخه پایتون ۲ و ۳ را روی رایانه خود دارید، توصیه میکنیم یک محیط مجازی پایتون ۳ نصب کنید که میتوانید با استفاده از -p flag مانند این عمل کنید:
virtualenv -p python3 my_env
با فعال کردن آن به صورت زیر، وارد محیط مجازی (virtualenv) تازه ایجاد شده خود شوید:
source my_env/bin/activate
با مشاهدهی اینکه نام محیط شما قبل از اعلان پوسته آمده است، تأیید کنید که در محیط هستید، یعنی
(my_env) $
حالا باید بتوانید بستههای مورد نیاز را pip install ، کد را درون این eivonment اجرا کنید و غیره. مزیت دیگر این است که اگر کاملاً آن را خراب کنید، در شرایطی قرار بگیرید که نصب پایتون شما خراب شود و غیره، میتوانید کل این محیط را بدون تأثیر بر بقیه سیستم خود از بین ببرید.
۵. کتابخانه کلاینت APIهای گوگل برای پایتون را نصب کنید
این آزمایشگاه کد نیاز به استفاده از کتابخانه کلاینت APIهای گوگل برای پایتون دارد، بنابراین یا یک فرآیند نصب ساده است، یا ممکن است اصلاً لازم نباشد کاری انجام دهید.
ما قبلاً برای راحتی شما استفاده از Cloud Shell را توصیه کردیم. میتوانید کل آموزش را از طریق یک مرورگر وب در فضای ابری انجام دهید. دلیل دیگر استفاده از Cloud Shell این است که بسیاری از ابزارهای توسعه محبوب و کتابخانههای لازم از قبل نصب شدهاند .
* نصب کتابخانههای کلاینت
( اختیاری ) اگر از Cloud Shell یا یک محیط محلی که قبلاً کتابخانههای کلاینت را نصب کردهاید استفاده میکنید، میتوانید از این مرحله صرف نظر کنید. فقط در صورتی که به صورت محلی در حال توسعه هستید و آنها را نصب نکردهاید (یا مطمئن نیستید که نصب کردهاید) باید این کار را انجام دهید. سادهترین راه استفاده از pip (یا pip3 ) برای نصب است (از جمله بهروزرسانی خود pip در صورت لزوم):
pip install -U pip google-api-python-client oauth2client
نصب را تأیید کنید
این دستور کتابخانه کلاینت و همچنین هر بستهای که به آن وابسته است را نصب میکند. چه از Cloud Shell استفاده کنید و چه از محیط خودتان، با وارد کردن بستههای لازم، نصب کتابخانه کلاینت را تأیید کنید و مطمئن شوید که هیچ خطایی در وارد کردن (و خروجی) وجود ندارد:
python3 -c "import googleapiclient, httplib2, oauth2client"
اگر به جای آن از پایتون ۲ (از Cloud Shell) استفاده کنید، هشداری دریافت خواهید کرد که پشتیبانی از آن منسوخ شده است:
******************************************************************************* Python 2 is deprecated. Upgrade to Python 3 as soon as possible. See https://cloud.google.com/python/docs/python2-sunset To suppress this warning, create an empty ~/.cloudshell/no-python-warning file. The command will automatically proceed in seconds or on any key. *******************************************************************************
وقتی بتوانید دستور import "test" را با موفقیت اجرا کنید (بدون خطا/خروجی)، آمادهاید تا با APIهای گوگل کار کنید!
خلاصه
از آنجایی که این یک آزمایشگاه کد مقدماتی است، فرض بر این است که شما در استفاده از APIهای گوگل و Google Workspace تازهکار هستید. اگر از قبل در ایجاد پروژهها و ایجاد «شناسههای کلاینت OAuth» برای احراز هویت کاربر تجربه دارید، یک پروژه موجود ایجاد یا دوباره استفاده کنید، یک شناسه کلاینت OAuth موجود ایجاد یا دوباره استفاده کنید و دو ماژول بعدی را رد کنید و مستقیماً به «نمایش برنامه فایلها و پوشههای Drive» بروید یا به «استفاده پیشرفته از کنسول توسعه» بروید تا آن مراحل را با راهنمایی کمتری مرور کنید.
۶. پروژه را در کنسول ابری مشخص کنید
یک برنامه که از APIهای گوگل استفاده میکند، به یک پروژه نیاز دارد. این پروژهها در کنسول توسعهدهندگان گوگل کلود یا به اختصار "devconsole" مدیریت میشوند. در این آزمایشگاه کد، ما فقط از API گوگل درایو استفاده خواهیم کرد، بنابراین یک لینک جادویی (در مرحله ۱) داریم که:
- شما را به کنسول توسعهدهندگان میبرد
- شما را در ایجاد یک پروژه جدید (یا انتخاب یک پروژه موجود) راهنمایی میکند، و
- به طور خودکار Drive API را فعال میکند
بذار انجامش بده!
- به console.developers.google.com/start/api?id=drive بروید و به حساب گوگل خود وارد شوید.
- اگر هنوز هیچ پروژهای ندارید، این صفحه را برای پذیرش شرایط خدمات APIهای گوگل مشاهده خواهید کرد:
پس از پذیرش شرایط، یک پروژه جدید با نام « پروژه من » ایجاد میشود و Drive API به طور خودکار فعال میشود. ۳. اگر در عوض، قبلاً یک پروژه ایجاد کردهاید (شاید آزمایشگاه کد قبلی شما؟)، این صفحه را مشاهده خواهید کرد: 
وقتی روی منوی کشویی «ایجاد پروژه» کلیک میکنید، میتوانید یک پروژه موجود را انتخاب کنید یا واقعاً یک پروژه جدید ایجاد کنید. 
پس از انتخاب (پروژه جدید یا موجود)، Drive API به طور خودکار برای شما فعال میشود. ۴. با این تأیید، متوجه خواهید شد که Drive API فعال شده است: 
۵. برای رفتن به مرحله بعدی، روی «برو به اعتبارنامهها» کلیک کنید.
۷. *مجوزدهی درخواستهای API (مجوز کاربر)
اگر قبلاً اعتبارنامههای مجوز حساب کاربری را ایجاد کردهاید و با فرآیند آن آشنا هستید، میتوانید از این بخش صرف نظر کنید. این بخش با مجوز حساب سرویس که تکنیک آن متفاوت است، متفاوت است، بنابراین لطفاً در ادامه ادامه دهید.
مقدمهای بر مجوزدهی (بهعلاوهی برخی احراز هویتها)
برای ارسال درخواست به APIها، برنامه شما باید مجوز مناسب را داشته باشد. Authentication ، کلمهای مشابه، اعتبارنامههای ورود به سیستم را توصیف میکند - شما هنگام ورود به حساب گوگل خود با نام کاربری و رمز عبور، خود را تأیید میکنید. پس از تأیید اعتبار، مرحله بعدی این است که آیا شما - یا بهتر بگوییم، کد شما - مجاز به دسترسی به دادهها، مانند فایلهای blob در Cloud Storage یا فایلهای شخصی کاربر در Google Drive هستید یا خیر.
APIهای گوگل از چندین نوع مجوز پشتیبانی میکنند، اما رایجترین نوع آن برای کاربران API گوگل ورکاسپیس، مجوز کاربر است، زیرا برنامه نمونه در این آزمایشگاه کد به دادههای متعلق به کاربران نهایی دسترسی دارد. این کاربران نهایی باید به برنامه شما اجازه دسترسی به دادههای خود را بدهند. این بدان معناست که کد شما باید اعتبارنامههای حساب کاربری OAuth2 را دریافت کند.
برای دریافت اعتبارنامههای OAuth2 برای مجوزدهی کاربر، به مدیریت API برگردید و تب «اعتبارنامهها» را در منوی سمت چپ انتخاب کنید:
وقتی به آنجا رسیدید، تمام اعتبارنامههای خود را در سه بخش جداگانه مشاهده خواهید کرد:
اولی برای کلیدهای API ، دومی برای شناسههای کلاینت OAuth 2.0 و آخری برای حسابهای سرویس OAuth2 است - ما از وسطی استفاده میکنیم.
ایجاد اعتبارنامهها
از صفحه اعتبارنامهها، روی دکمه + ایجاد اعتبارنامهها در بالا کلیک کنید، که سپس یک کادر محاورهای به شما میدهد که در آن «OAuth client ID:» را انتخاب میکنید.
در صفحه بعد، دو اقدام پیش رو دارید: پیکربندی «صفحه رضایت» برای مجوز برنامهتان و انتخاب نوع برنامه:
اگر صفحه رضایتنامه تنظیم نکرده باشید، هشدار را در کنسول مشاهده خواهید کرد و باید همین حالا این کار را انجام دهید. (اگر صفحه رضایتنامه شما از قبل تنظیم شده است، از این مراحل بعدی صرف نظر کنید.)
صفحه رضایت OAuth
روی «صفحه پیکربندی رضایت» کلیک کنید و در آنجا یک برنامه «خارجی» (یا اگر مشتری Google Workspace [قبلاً «Google Workspace»] هستید، «داخلی») را انتخاب کنید:
توجه داشته باشید که برای اهداف این تمرین، فرقی نمیکند کدام را انتخاب کنید زیرا نمونه کد آزمایشگاه خود را منتشر نمیکنید. اکثر افراد برای رفتن به یک صفحه پیچیدهتر، گزینه "External" را انتخاب میکنند، اما شما فقط باید فیلد "Application name" را در بالا تکمیل کنید:
تنها چیزی که در حال حاضر نیاز دارید، یک نام برای برنامه است، بنابراین نامی را انتخاب کنید که منعکس کننده آزمایشگاه کدی باشد که شما انجام میدهید، سپس روی ذخیره کلیک کنید.
ایجاد شناسه کلاینت OAuth (احراز هویت کاربر)
حالا به تب Credentials برگردید تا یک شناسه کلاینت OAuth2 ایجاد کنید. در اینجا میتوانید انواع شناسههای کلاینت OAuth را که میتوانید ایجاد کنید، مشاهده کنید:
ما در حال توسعه یک ابزار خط فرمان هستیم که Other نام دارد، بنابراین آن را انتخاب کنید و سپس روی دکمه Create کلیک کنید. یک نام برای شناسه کلاینت انتخاب کنید که منعکس کننده برنامهای باشد که در حال ایجاد آن هستید یا به سادگی نام پیشفرض را که معمولاً "Other client N " است، در نظر بگیرید.
ذخیره اعتبارنامههای شما
- یک کادر محاورهای با اطلاعات کاربری جدید ظاهر میشود؛ برای بستن، روی تأیید کلیک کنید.
- به صفحه اعتبارنامهها برگردید، به پایین اسکرول کنید تا به بخش «OAuth2 Client IDs» برسید، آیکون دانلود را پیدا کرده و روی آن کلیک کنید.
در پایین سمت راست شناسه کلاینت تازه ایجاد شده شما.
- این کار یک پنجره محاورهای برای ذخیره فایلی با نام
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.jsonباز میکند که احتمالاً در پوشه دانلودهای شما قرار دارد. توصیه میکنیم آن را به نامی سادهتر مانندclient_secret.json(که برنامه نمونه از آن استفاده میکند) کوتاه کنید، سپس آن را در دایرکتوری/پوشهای که برنامه نمونه را در این آزمایشگاه کد ایجاد خواهید کرد، ذخیره کنید.
خلاصه
با در دست داشتن اطلاعات احراز هویت، اکنون آماده دسترسی به Drive API از طریق برنامه خود هستید، البته با در نظر گرفتن هدف از شناسه کلاینت OAuth این است که کاربران شما باید به برنامه شما اجازه دسترسی به دادههای خود در Google Drive را بدهند.
توجه : جزئیات بیشتر در مورد ایجاد پروژهها، فعال کردن APIها و دریافت اعتبارنامهها، به صورت دستی، یعنی بدون استفاده از "ویزارد" فوق، پس از پایان این آزمایشگاه کد برای مطالعه بیشتر در دسترس است.
۸. نمایش برنامهی فایلها و پوشههای درایو شما
چه در محیط توسعه محلی خود و چه در Cloud Shell، در همان دایرکتوری که فایل اعتبارنامه client_id.json شما قرار دارد، یک فایل پایتون جدید با نام drive_list.py ایجاد کنید و خطوط کد زیر را به آن اضافه کنید:
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
ساختار برنامه
این اپلیکیشن سه بخش اصلی دارد:
- پایتون برای آوردن قابلیتهای کتابخانه، دستورات را وارد میکند
- اخذ مدارک درخواست
- دریافت نام فایلها و پوشهها و MIMEtypeها در گوگل درایو کاربر و نمایش آنها
توجه : بررسی عمیقتر کد و بررسی توضیح خط به خط آن، پس از پایان این آزمایشگاه کد برای مطالعه بیشتر در دسترس است.
اجرای برنامه
نام این فایل را چیزی شبیه به drive_list.py بگذارید. اولین باری که اسکریپت را اجرا میکنید، مجوز دسترسی به فایلهای کاربر در Drive (فایل شما) را نخواهد داشت. خروجی با توقف اجرا به این شکل خواهد بود:
$ python3 ./drive_list.py /usr/local/lib/python3.6/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Your browser has been opened to visit: https://accounts.google.com/o/oauth2/auth?client_id=LONG-STRING.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2F&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
از محیط توسعه محلی
اسکریپت خط فرمان متوقف میشود و یک پنجره مرورگر باز میشود و پنجره مجوزهای OAuth2 را به شما نمایش میدهد:
اینجاست که برنامه از کاربر مجوزهایی را که کد درخواست میکند (از طریق متغیر SCOPES ) درخواست میکند. در این حالت، این امکان مشاهده ابردادههای فایل از Google Drive کاربر است. بله، در کد شما، این محدودههای مجوز به صورت URI ظاهر میشوند، اما به زبانی که توسط زبان محلی شما در پنجره گفتگوی جریان OAuth2 مشخص شده است، ترجمه میشوند. کاربر باید مجوز صریحی برای مجوز(های) درخواستی ارائه دهد، در غیر این صورت بخش "اجرای جریان" کد یک استثنا ایجاد میکند و اسکریپت ادامه نمییابد.
توجه : برخی از کاربران چندین مرورگر دارند و ممکن است درخواست مجوز در مرورگری که ترجیح نمیدهند نمایش داده شود. در این صورت، کافیست کل URL را از پنجره مرورگری که نمیخواهید استفاده کنید کپی کرده و در نوار آدرس مرورگری که میخواهید استفاده کنید، جایگذاری کنید.
از پوسته ابری
اگر حواستان نبود و برنامه را در Cloud Shell اجرا میکردید، هیچ پنجره مرورگری باز نمیشد و شما را گیر میانداخت. متوجه باشید که پیام تشخیصی در پایین برای شما در نظر گرفته شده بود... این یکی:
If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
وقتی آن را به این روش اجرا کنید، به جای آن خروجی زیر را دریافت خواهید کرد:
$ python3 drive_list.py --noauth_local_webserver /usr/local/lib/python3.7/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Go to the following link in your browser: https://accounts.google.com/o/oauth2/auth?client_id=xxx.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code Enter verification code:
با دنبال کردن دستورالعملها و رفتن به یک تب مرورگر دیگر با آن URL، تجربهای تقریباً مشابه آنچه در بالا برای محیطهای توسعه محلی توضیح داده شد، خواهید داشت. تفاوت کلیدی در انتها است که یک صفحه دیگر با کد تأیید برای وارد کردن در Cloud Shell دریافت میکنید:
این کد را کپی کرده و در پنجره ترمینال پیست کنید.
خلاصه
به محض اینکه کاربر روی دکمهی «اجازه دادن» کلیک کند و/یا کد تأیید در اعلان وارد شود، برنامه (به اجرا) ادامه میدهد، بنابراین انتظار داشته باشید خروجی شامل فایلها/پوشههای Drive و MIMEtypeهای آنها را مشاهده کنید. در اینجا مثالی از یکی از حسابهای آزمایشی ما آورده شده است:
$ python3 ./drive_list.py Travel expenses application/vnd.google-apps.spreadsheet Gmail Add-ons codelab application/vnd.google-apps.script Google Workspace Developer Intro application/vnd.google-apps.presentation Baseball Sheets application/vnd.google-apps.folder My Resume application/vnd.google-apps.document . . .
توجه داشته باشید که در اجراهای متوالی، دیگر از شما درخواست مجوز نمیشود (زیرا توسط کتابخانههای auth ذخیره شده است) و مستقیماً به خروجی میروید. آیا دیدن اسنادتان در ترمینال برای اولین بار هیجانانگیز نیست؟ ما فکر میکنیم همینطور است!
۹. نتیجهگیری
حالا آمادهاید تا ویژگیهای بیشتری در مورد رابط برنامهنویسی کاربردی درایو (Drive API) یاد بگیرید یا سایر فضاهای کاری گوگل (Gmail، Google Docs، Sheets، Slides، Calendar) و سایر رابطهای برنامهنویسی کاربردی گوگل (Maps، Analytics، YouTube و غیره) را بررسی کنید. تبریک میگوییم که تا انتها پیش رفتید!
کدی که در این آزمایشگاه کد ارائه شده است، در مخزن گیتهاب آن به آدرس github.com/googlecodelabs/gsuite-apis-intro نیز موجود است. (هدف ما این است که این آزمایشگاه کد با مخزن هماهنگ باشد.) آماده ادامه دادن هستید؟ در زیر منابع مختلفی وجود دارد که میتوانید برای کمک به شما در بررسی بیشتر مطالب پوشش داده شده در این آزمایشگاه کد، یا اگر میخواهید ذهن خود را به کار بیندازید و راههای دیگری برای دسترسی به فناوریهای گوگل از طریق برنامهنویسی را بررسی کنید، به آنها دسترسی پیدا کنید.
همانطور که قبلاً اشاره شد، اگر شما یک توسعهدهندهی معمولی پایتون نیستید، از شما دعوت میکنیم این مثال codelab را به زبان توسعهی مورد علاقهی خود دوباره انجام دهید. کتابخانههای کلاینت برای زبانهای پشتیبانیشده در اینجا موجود است.
مطالعه تکمیلی
حالا که کمی با Drive API آشنایی پیدا کردهاید، در ادامه چند تمرین برای توسعه بیشتر مهارتهایتان پیشنهاد شده است:
- فایلهای ZIP : برنامهای بنویسید که از چندین آرشیو ZIP در Drive پشتیبانگیری کند و آنها را درجا از حالت فشرده خارج کند، به طوری که نام هر فایل ZIP، نام پوشهای باشد که فایلها در آن قرار میگیرند. امتیاز ویژه: از آرشیوهای ZIP بازگشتی در فایلهای ZIP دیگر با پوشههای Drive تعبیهشده در پوشههای دیگر پشتیبانی میکند. اگر منصرف شدید، این برنامه نمونه Node.js را ببینید.
- آلبومهای عکس : شروع یک ابزار تولید آلبوم عکس را بنویسید که چندین تصویر را در گوگل درایو آپلود میکند و آنها را بر اساس زمان و موقعیت جغرافیایی در پوشههای جداگانه سازماندهی میکند. اعتبار بیشتر: یک کتابخانه دستکاری تصویر متنباز پیدا کنید و تمام عکسها را در هر پوشه به گونهای قرار دهید که نمایانگر رویدادهایی باشند که ممکن است تجربه کرده باشید (یک سفر، یک شام و غیره).
- کاوش GCP : برنامهای بنویسید که Google Workspace و Google Cloud Platform (GCP) را به هم متصل کند. ابزاری بنویسید که از فایلهای تصویری از Google Drive در Google Cloud Storage (GCS)، یکی دیگر از راهحلهای "ذخیرهسازی فایل در فضای ابری"، نسخه پشتیبان تهیه کند. باور کنید یا نه، استفاده از GCS به دلیل کتابخانههای کلاینت پیشرفتهاش، سادهتر از Drive خواهد بود.
- تحلیل و ثبت : با تحلیل هر تصویر پشتیبانگیری شده و ارسال آن به API گوگل کلود ویژن و دریافت «برچسبهای» برتر (۳، ۵، ۱۰) آنچه API در آن تصاویر میبیند، راهحل خود را به شماره ۳ گسترش دهید. برای هر تصویر، یک ردیف در یک گوگل شیت بنویسید که شامل تحلیل از کلود ویژن و همچنین مکان پشتیبانگیری آن در GCS باشد. اگر منصرف شدید، به این آزمایشگاه کد پایتون مراجعه کنید.
۱۰. منابع اضافی
مستندات
- مستندات API گوگل درایو (REST API و SDK/API بومی اندروید)
- سایر مستندات APIهای Google Workspace
- سایر مستندات APIهای گوگل
- کتابخانههای کلاینت APIهای گوگل
- مستندات OAuth2
ویدیوهای مرتبط و عمومی
- ایجاد پروژههای جدید Google API ( پست وبلاگ و ویدیو )
- بررسی کد boilerplate مجوز پایتون ( ویدئو )
- فهرست کردن فایلهای شما در گوگل درایو ( ویدئو ، پست وبلاگ )
- کتابخانه ویدیویی API گوگل درایو
- مجموعه ویدیویی Launchpad Online (قبل از...)
- مجموعه ویدیویی نمایش توسعهدهندگان فضای کاری گوگل
اخبار و بهروزرسانیها
- وبلاگ توسعهدهندگان Google Workspace
- توسعهدهندگان گوگل ورکاسپیس، توییتر (@GSuiteDevs)
- خبرنامه ماهانه توسعهدهندگان Google Workspace
سایر آزمایشگاههای کد
مقدماتی
- [اسکریپت برنامهها] مقدمهای بر اسکریپت برنامههای گوگل
متوسط
- [اسکریپت برنامهها] ابزار خط فرمان اسکریپت برنامههای CLASP
- [اسکریپت برنامهها] افزونههای جیمیل
- [اسکریپت برنامهها] افزونه اسناد و GCP رابط برنامهنویسی کاربردی زبان طبیعی
- [اسکریپت برنامهها] چارچوب ربات چت Hangouts
- [REST APIs] ابزار گزارشگیری سفارشی (Sheets API)
- [رابطهای برنامهنویسی REST] تولیدکننده اسلاید سفارشی برای مجوز گیتهاب، تحلیلگر BigQuery (اسلایدها+رابطهای برنامهنویسی BigQuery)
پیشرفته
- [رابطهای برنامهنویسی کاربردی REST] گردش کار پردازش تصویر ابری (درایو، فضای ذخیرهسازی ابری، دید ابری، رابطهای برنامهنویسی کاربردی Sheets)
برنامههای مرجع
- مبدل Markdown به Google Slides (رابط برنامهنویسی نرمافزار Slides REST)
۱۱. *توضیحات دقیق برنامه
این بخش اختیاری پس از پایان جلسه به عنوان خودآموز برای پر کردن هرگونه شکافی که ممکن است ایجاد شده باشد یا برای تحقیقات بیشتر مورد استفاده قرار میگیرد.
پایتون برای آوردن قابلیتهای کتابخانه، دستورات را وارد میکند
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
- اولین دستور
importاین کد را قادر میسازد تا روی پایتون ۲ اجرا شود - اگر فقط از پایتون ۳ استفاده میکنید، میتوانید آن را به طور کامل حذف کنید. - یکی از دستورالعملهای سبک پایتون، جداسازی ایمپورتهای کتابخانه استاندارد و ماژولهای شخص ثالث است - خط خالی برای همین منظور در نظر گرفته شده است.
- سه دستور بعدی، کلاسها و توابع لازم را از کتابخانه کلاینت APIهای گوگل وارد میکنند... همه آنها برای نوشتن این برنامه مورد نیاز ما هستند. به طور خلاصه، نحوه انجام آنها به شرح زیر است:
-
googleapiclientبر اتصال به API های گوگل تمرکز دارد -
httplib2یک کلاینت HTTP برای استفادهی برنامه فراهم میکند. -
oauth2clientبه ما در مدیریت اعتبارنامههای OAuth2 کمک میکند.
اخذ مجوز و مدارک لازم برای درخواست
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
SCOPESبرنامه، مجوزهایی هستند که یک برنامه از کاربر در حال اجرای آن درخواست میکند. برای حفظ امنیت دادههای کاربر، برنامهها بدون دریافت مجوز نمیتوانند اجرا شوند.- بهترین روش این است که از محدودترین مجوزهایی که برنامه شما برای عملکرد خود نیاز دارد استفاده کنید. چرا؟
- آیا آزاردهنده نیست وقتی یک برنامه هنگام نصب یا اجرای آن، مجموعه بزرگی از مجوزها را درخواست میکند؟ حدس بزنید چه شده؟ شما اکنون در روی دیگر سکه هستید و از کاربران خود همه این مجوزها را درخواست میکنید. استفاده از حوزههای محدودتر باعث میشود کاربران در مورد نصب برنامه شما احساس بهتری داشته باشند زیرا شما دسترسی کمتری را درخواست میکنید.
- تقریباً همه دامنهها شبیه URLهای طولانی هستند و دامنه فراداده Drive نیز از این قاعده مستثنی نیست.
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
- برای ارتباط برنامهها با سرورهای گوگل، به یک توکن نیاز است. توکنهای معتبری که از گوگل برمیگردند، در فایل ذخیرهسازی توکن،
storage.json، ذخیره میشوند. اگر این توکنها را ذخیره نکنید، هر بار که برنامه خود را اجرا میکنید، باید دوباره آن را تأیید کنید.
store = file.Storage('storage.json')
- این برنامه ابتدا بررسی میکند که آیا اعتبارنامههای معتبری از قبل در حافظه داریم یا خیر (به بخش شرطی دستور
ifمراجعه کنید).
creds = store.get()
if not creds or creds.invalid:
- اگر هیچ اعتبارنامهای ندارید یا اعتبارنامههایتان منقضی شده است، باید یک جریان مجوز جدید [از طریق
oauth2client.client.flow_from_clientsecrets()] از شناسه کلاینت OAuth و رمز موجود در فایلclient_id.jsonکه دانلود کردهاید، ساخته شود.
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
- وقتی برنامه شما یک جریان (flow) داشته باشد، باید اجرا شود تا صفحه مجوزهای OAuth2 را که در بالا توضیح داده و نشان داده شده است، به کاربر ارائه دهد [از طریق
oauth2client.tools.run_flow()].
creds = tools.run_flow(flow, store)
- با کلیک روی «اجازه دادن» ، کاربران به برنامه شما اجازه دسترسی به فرادادههای فایل گوگل درایو خود را میدهند و سرورهای گوگل توکنهایی را برای دسترسی به API برمیگردانند. این توکنها به عنوان
credsبرگردانده شده و در فایلstorage.jsonذخیره میشوند. - در این مرحله، برنامه شما اکنون اعتبارنامههای معتبری برای برقراری تماسهای API دارد. فراخوانی
googleapiclient.discovery.build()یک نقطه پایانی سرویس برای API مورد استفاده شما ایجاد میکند. - برای استفاده از
build()، نام API ('drive') و نسخه مورد نظر (در حال حاضر'v3') را وارد کنید. - پارامتر آخر یک کلاینت HTTP است که برای فراخوانیهای رمزگذاریشده API استفاده میشود.
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
دریافت و نمایش ۱۰۰ فایل/پوشه اول و انواع MIME درایو
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
- خط بعدی کد، متد
list()را در مجموعهfiles()برای API درایو فراخوانی میکند تا درخواست را بسازد، که بلافاصله باexecute()فراخوانی میشود. یکdictپایتون برگردانده میشود که از آن کلید'files'را برای دریافت ۱۰۰ نام فایل و پوشه از گوگل درایو کاربر (یا کمتر اگر فایلهای کمتری دارید) درخواست میکنیم. - چرا ۱۰۰؟ این مقدار پیشفرض
DRIVE.files().list()است. اگر میخواهید این عدد را تغییر دهید، مثلاً فقط به ۱۰ فایل یا ۱۰۰۰ فایل، پارامترpageSizeرا به درخواست خود اضافه کنید:DRIVE.files().list(pageSize=10). در اینجا مستندات مربوط به گزینههای بیشتر آمده است. - بخش پایانی اسکریپت، هر فایل را پیمایش میکند و نام و MIMEtype فایل آنها را نمایش میدهد.
شما اکنون اولین برنامه خود را که از API REST گوگل استفاده میکند، نوشتهاید... تبریک میگویم! گذشته از کد واردات و مجوزدهی، این اسکریپت واقعاً فقط چند خط کد است (آنچه در بالا میبینید). اکثر APIهای گوگل به روشی مشابه کار میکنند و شما فقط باید برای هر کدام که میخواهید استفاده کنید، نقاط پایانی سرویس ایجاد کنید.
استفاده از بیش از یک API گوگل در یک برنامه
بله، مطمئناً میتوانید از بیش از یک API در یک برنامه استفاده کنید! در اینجا یک قطعه کد پایتون برای برنامهای که از یک کلاینت HTTP مشابه استفاده مجدد میکند و نقاط پایانی سرویس را برای سه API گوگل ایجاد میکند (بله، همچنین با ۳ SCOPES مختلف):
SCOPES = (
'https://www.googleapis.com/auth/drive',
'https://www.googleapis.com/auth/spreadsheets.readonly',
'https://www.googleapis.com/auth/presentations',
)
. . .
HTTP = creds.authorize(Http())
DRIVE = discovery.build('drive', 'v3', http=HTTP)
SHEETS = discovery.build('sheets', 'v4', http=HTTP)
SLIDES = discovery.build('slides', 'v1', http=HTTP)
ما تصور میکنیم که این کد میتواند بخشی از برنامهای باشد که چندین دسته اسلاید (Slides API) را بر اساس دادههای صفحه گسترده (Sheets API) تولید میکند و از یک الگوی اسلاید که برای هر دسته تولید شده کپی میشود (Drive API) استفاده میکند. اگرچه چنین برنامهای وجود ندارد، شما باید بتوانید با استفاده از دو نمونه موجود که تیم Google Workspace به عنوان بلوکهای سازنده ایجاد کرده است، چیزی مشابه بسازید:
- جایگزینی متن و تصاویر در اسلایدها ( پست وبلاگ و ویدیو ) - از Drive API برای کپی کردن یک دسته قالب اسلاید استفاده میکند و سپس از Slides API برای تغییر متغیرهای متن و تصویر استفاده میکند.
- تولید اسلاید از دادههای صفحهگسترده ( پست وبلاگ و ویدیو ) — دادهها را از یک صفحهگسترده (Sheets API) میخواند و بر اساس آن دادهها اسلایدها (Slides API) ایجاد میکند.
چالش شما: ساخت آن اپلیکیشن!
۱۲. *استفاده پیشرفته از کنسول توسعه
در این بخش اختیاری، نحوه ایجاد پروژهها در کنسول توسعهدهندگان، فعال کردن APIها و دریافت اعتبارنامهها را شرح میدهیم، همه بدون استفاده از ویزارد همانطور که در بالا در codelab ذکر شد. این بخش برای کاربران سطح متوسط است که به اندازه کافی راحت هستند که این کار را به صورت دستی انجام دهند یا مایل به یادگیری نحوه انجام آن هستند.
پروژه را در کنسول Cloud مشخص کنید
هر زمان که با استفاده از APIهای گوگل برنامهای مینویسید، به یک پروژه نیاز دارید. میتوانید از یک پروژه موجود دوباره استفاده کنید یا یک پروژه جدید ایجاد کنید. این کار در کنسول ابری (Cloud Console) انجام میشود. برخی از آزمایشگاههای کد یک لینک جادویی (مثلاً مانند یک ویزارد راهاندازی) ارائه میدهند که شما را به سرعت به کار میاندازد و بسیاری از مراحل مورد نیاز را حذف میکند. اما همه آنها این کار را نمیکنند، بنابراین این دستورالعملها به عنوان دستورالعملهای کلی در مورد نحوه ایجاد پروژهها در نظر گرفته شدهاند.
شما میتوانید از اکثر صفحات کنسول ابری، پروژه ایجاد کنید، البته تا زمانی که با اطلاعات کاربری گوگل خود وارد شده باشید و منوی کشویی پروژه را در بالای کنسول مشاهده کنید. توجه داشته باشید که اکثر اسکرینشاتهای اینجا از API Manager یا همان Developers Console گرفته شدهاند (که به راحتی با کلیک روی «API manager» در منوی سمت چپ یا با هدایت مستقیم مرورگر خود به console.developers.google.com قابل دسترسی است).
- اگر هنوز هیچ پروژهای ندارید، ممکن است به ... برده شوید.
- صفحه داشبورد :
- صفحه کتابخانه :
- یا یک صفحه کاملاً خالی:
اگر این مورد سوم برای شما اتفاق افتاد، کافیست مرورگر را رفرش کنید تا به صفحه کتابخانه منتقل شوید.
- چه در صفحات داشبورد باشید و چه در صفحات کتابخانه ، روی انتخابگر پروژه در بالای صفحه کلیک کنید:
- Next, you'll get the selector dialog. Click on the "+" on the right-hand side to create a new project:
- After you click the "+", a New Project page will appear. All consumer accounts get 12 projects by default. Before creating your first project, you'll have to accept the Google APIs Terms of Service :
After you've done this, the email solicitation and Terms of Service questions go away when creating future projects:
You've now created a project successfully and are ready to move on by choosing the APIs you wish to use for your project.
Enable Google APIs
Before you can begin using Google APIs, you must enable them. The example below shows what you would do to enable the Cloud Vision API. In this codelab, you may be using one or more APIs, and should follow similar steps to enable them before usage.
از پوسته ابری
Using Cloud Shell, you can enable the API by using the following command:
gcloud services enable vision.googleapis.com
From the Cloud Console
You may also enable the Vision API in the API Manager. From the Cloud Console, go to API Manager and select, "Library."
In the search bar, start typing, "vision," then select Vision API when it appears. It may look something like this as you're typing:
Select the Cloud Vision API to get the dialog you see below, then click the "Enable" button:
هزینه
While many Google APIs can be used without fees, use of GCP (products & APIs) is not free. When enabling the Vision API (as described above), you may be asked for an active billing account. The Vision API's pricing information should be referenced by the user before enabling. Keep in mind that certain Google Cloud Platform (GCP) products feature an "Always Free" tier for which you have to exceed in order to incur billing. For the purposes of the codelab, each call to the Vision API counts against that free tier, and so long as you stay within its limits in aggregate (within each month), you should not incur any charges.
Some Google APIs, ie, Google Workspace, has usage covered by a monthly subscription, so there's no direct billing for use of the Gmail, Google Drive, Calendar, Docs, Sheets, and Slides APIs, for example. Different Google products are billed differently, so be sure to reference your API's documentation for that information.
خلاصه
In this codelab, you only need to turn on the Google Drive API, so follow the instructions above and search for "Drive". Proceed forward once it's enabled.
Authorize API requests (user authorization)
Intro to authorization (plus some authentication)
In order to make requests to the APIs, your application needs to have the proper authorization . Authentication , a similar word, describes login credentials—you authenticate yourself when logging into your Google account with a login & password. Once authenticated, the next step is whether you are—or rather, your code , is— authorized to access data, such as blob files on Cloud Storage or a user's personal files on Google Drive.
Google APIs support several types of authorization, but the one most common for Google Workspace API users is user authorization since the example application in this codelab accesses data belonging to end-users. Those end-users must grant permission for your app to access their data . This means your code must obtain user account OAuth2 credentials.
To get OAuth2 credentials for user authorization, go back to the API manager and select the "Credentials" tab on the left-nav:
When you get there, you'll see all your credentials in three separate sections:
The first is for API keys , the second OAuth 2.0 client IDs, and the last OAuth2 service accts —we're using the one in the middle.
Creating credentials
From the Credentials page, click on the + Create Credentials button at the top, which then gives you a dialog where you'd choose "OAuth client ID:"
On the next screen, you have 2 actions: configuring your app's authorization "consent screen" and choosing the application type:
If you have not set a consent screen, you will see the warning in the console and would need to do so now. (Skip this these next steps if your consent screen has already been setup.)
OAuth consent screen
Click on "Configure consent screen" where you select an "External" app (or "Internal" if you're a Google Workspace customer):
Note that for the purposes of this exercise, it doesn't matter which you pick because you're not publishing your codelab sample. Most people will select "External" to be taken to a more complex screen, but you really only need to complete the "Application name" field at the top:
The only thing you need at this time is just an application name so pick someone that reflects the codelab you're doing then click Save .
Creating OAuth client ID (user acct auth)
Now go back to the Credentials tab to create an OAuth2 client ID . Here you'll see a variety of OAuth client IDs you can create:
We're developing a command-line tool, which is Other , so choose that then click the Create button. Choose a client ID name reflecting the app you're creating or simply take the default name, which is usually, "Other client N ".
Saving your credentials
- A dialog with the new credentials appears; click OK to close
- Back on the Credentials page, scroll down to the "OAuth2 Client IDs" section find and click the download icon
- This open a dialog to save a file named
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, likely to your Downloads folder. We recommend shortening to an easier name likeclient_secret.json(which is what the sample app uses), then save it to the directory/folder where you'll be creating the sample app in this codelab.