درباره این codelab
1. استفاده از APIهای Google Workspace
این لبه کد شما را با استفاده از Google Workspace (G Suite سابق) مبتنی بر HTTP RESTful APIها آشنا می کند. مثال برای خلاصه و در دسترس بودن در پایتون انجام می شود، اما می توانید از زبان توسعه دلخواه خود نیز استفاده کنید. شما در معرض موضوعات مقدماتی مانند نحوه استفاده از کنسول توسعه دهنده برای ایجاد/مدیریت پروژه ها، دریافت اعتبارنامه مجوز و نصب کتابخانه های سرویس گیرنده API خواهید بود. با رعایت تشریفات، برنامه ای می نویسید تا با استفاده از API، 100 فایل و پوشه اول را در Google Drive خود نمایش دهد.
چیزی که یاد خواهید گرفت
- با استفاده از Google/Cloud Developers Console یک پروژه ایجاد کنید
- اعتبارنامه برنامه OAuth2 را در برنامه خود دریافت و استفاده کنید
- درباره استفاده از Google APIs Client Libraries بیاموزید
- برنامهها را با استفاده از APIهای Google و Google Workspace بنویسید
- اطلاعات فایل و پوشه را با Google Drive API دریافت کنید
آنچه شما نیاز دارید
- دسترسی به اینترنت و مرورگر وب
- یک حساب Google (حسابهای Google Workspace ممکن است به تأیید سرپرست نیاز داشته باشند)
- آشنایی با سیستم های سازگار با POSIX مانند Linux و Mac OS X
- امکان ایجاد فایل های منبع با ویرایشگر کد یا دستورات پوسته.
- مهارت های پایه در پایتون (2 یا 3)، اما می توانید از هر زبان پشتیبانی شده استفاده کنید
- برخی از فایلها و/یا پوشهها در Google Drive شما
2. نظرسنجی
چگونه از این آموزش Codelab استفاده خواهید کرد؟
تجربه خود را با ابزارها و APIهای برنامهنویس Google Workspace چگونه ارزیابی میکنید؟
3. نمای کلی
در این کد لبه یاد خواهید گرفت که چگونه:
- کتابخانه سرویس گیرنده Google APIs را برای پایتون دانلود کنید
- یک پروژه جدید در Google/Cloud Developers Console ایجاد کنید
- اعتبار لازم را برای اپلیکیشن خود دریافت کنید
- برای دسترسی به Google Drive API از این اعتبارنامه ها استفاده کنید
اگر ترجیح میدهید از پایتون استفاده نکنید، میتوانید نرمافزار کد را در ابزار توسعه مورد علاقهتان پیادهسازی کنید (کتابخانههای کلاینت زبانهای پشتیبانیشده در اینجا موجود است) و به سادگی به نمونههای پایتون به عنوان شبه کد (قابل اجرا) مراجعه کنید.
4. محیط پایتون را تایید کنید
این نرمافزار کد از شما میخواهد از زبان پایتون استفاده کنید (اگرچه بسیاری از زبانها توسط کتابخانههای سرویس گیرنده Google APIs پشتیبانی میشوند ، بنابراین با خیال راحت چیزی معادل آن را در ابزار توسعه مورد علاقه خود بسازید و به سادگی از Python به عنوان شبه کد استفاده کنید). به طور خاص، این کد لبه از پایتون 2 و 3 پشتیبانی می کند، اما توصیه می کنیم در اسرع وقت به 3.x بروید.
Cloud Shell یک ابزار راحتی است که مستقیماً از کنسول Cloud برای کاربران در دسترس است و به محیط توسعه محلی نیاز ندارد، بنابراین این آموزش را می توان به طور کامل در فضای ابری با یک مرورگر وب انجام داد. Cloud Shell مخصوصاً اگر در حال توسعه یا برنامهریزی برای ادامه توسعه با محصولات و APIهای GCP هستید مفید است. به طور خاص برای این کد، Cloud Shell قبلاً هر دو نسخه پایتون را از قبل نصب کرده است.
Cloud Shell همچنین IPython را نصب کرده است... این یک مفسر تعاملی پایتون سطح بالاتری است که ما آن را توصیه می کنیم، به خصوص اگر بخشی از جامعه علم داده یا یادگیری ماشین هستید. اگر هستید، IPython مفسر پیشفرض برای نوتبوکهای Jupyter و همچنین نوتبوکهای Colab ، Jupyter است که توسط Google Research میزبانی میشوند.
IPython ابتدا از یک مفسر Python 3 استفاده می کند اما اگر 3.x در دسترس نباشد به Python 2 برمی گردد. 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. >>>
Codelab همچنین فرض میکند که شما ابزار نصب pip
(مدیر بسته پایتون و حلکننده وابستگی) را دارید. همراه با نسخه های 2.7.9+ یا 3.4+ ارائه می شود. اگر نسخه پایتون قدیمیتری دارید، برای دستورالعملهای نصب به این راهنما مراجعه کنید. بسته به مجوزهای شما ممکن است نیاز به دسترسی sudo
یا superuser داشته باشید، اما معمولاً اینطور نیست. همچنین می توانید صریحاً از pip2
یا pip3
برای اجرای pip
برای نسخه های خاص پایتون استفاده کنید.
بقیه کدها فرض میکنند که شما از پایتون 3 استفاده میکنید—دستورالعملهای خاصی برای پایتون 2 ارائه میشوند اگر تفاوت قابل توجهی با 3.x داشته باشند.
*محیط های مجازی ایجاد و استفاده کنید
این بخش اختیاری است و فقط برای کسانی که باید از یک محیط مجازی برای این کد لبه استفاده کنند (بر اساس نوار کناری هشدار بالا) واقعاً مورد نیاز است. اگر فقط پایتون 3 را روی رایانه خود دارید، می توانید به سادگی این دستور را برای ایجاد یک virtualenv به نام my_env
صادر کنید (در صورت تمایل می توانید نام دیگری انتخاب کنید):
virtualenv my_env
با این حال، اگر هر دو پایتون 2 و 3 را روی رایانه خود دارید، توصیه میکنیم پایتون 3 virtualenv را نصب کنید که میتوانید با -p flag
به این صورت انجام دهید:
virtualenv -p python3 my_env
virtualenv تازه ایجاد شده خود را با «فعال کردن» به این صورت وارد کنید:
source my_env/bin/activate
تأیید کنید که در محیط هستید با مشاهده اینکه دستور پوسته شما اکنون با نام محیط شما قبل از آن قرار گرفته است، به عنوان مثال،
(my_env) $
حالا باید بتوانید هر بسته مورد نیاز pip install
، کد را در این eivonment اجرا کنید، و غیره. مزیت دیگر این است که اگر آن را کاملاً بهم بزنید، در شرایطی قرار بگیرید که نصب پایتون شما خراب شود و غیره، می توانید این را از بین ببرید. کل محیط بدون تأثیر بر بقیه سیستم شما.
5. کتابخانه سرویس گیرنده Google APIs را برای پایتون نصب کنید
این کد لبه نیاز به استفاده از کتابخانه سرویس گیرنده Google APIs برای پایتون دارد، بنابراین یا یک فرآیند نصب ساده است، یا ممکن است اصلاً مجبور نباشید کاری انجام دهید.
ما قبلاً توصیه کردیم برای راحتی از 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"
اگر به جای آن از Python 2 (از 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" را با موفقیت اجرا کنید (بدون خطا/خروجی)، آماده شروع صحبت با Google API هستید!
خلاصه
از آنجایی که این یک کد آزمایشگاهی مقدماتی است، فرض بر این است که شما در استفاده از Google و Google Workspace APIهای جدید هستید. اگر قبلاً تجربه ایجاد پروژهها و ایجاد مجوز کاربر "شناسههای مشتری OAuth" را دارید. اگر چنین است، یک پروژه موجود ایجاد کنید یا دوباره از آن استفاده کنید، یک شناسه مشتری OAuth موجود ایجاد کنید یا دوباره استفاده کنید و دو ماژول بعدی را رد کنید و مستقیماً به «نمایش برنامه فایلها و پوشههای Drive» بروید یا به «استفاده پیشرفته از کنسول devconsole» بروید. "، تا آن مراحل را با راهنمایی کمتر مرور کنید.
6. پروژه را در کنسول Cloud مشخص کنید
برنامه ای که از API های Google استفاده می کند به پروژه نیاز دارد. آنها در Google Cloud Developers Console یا به سادگی «devconsole» مدیریت میشوند. در این کد لبه، ما فقط از Google Drive API استفاده می کنیم، بنابراین یک پیوند جادویی (در زیر در مرحله 1) داریم که:
- شما را به devconsole می برد
- شما را در ایجاد یک پروژه جدید (یا انتخاب یک پروژه موجود) راهنمایی می کند
- به طور خودکار Drive API را فعال می کند
بگذار انجامش بده!
- به console.developers.google.com/start/api?id=drive بروید و به حساب Google خود وارد شوید.
- اگر هنوز هیچ پروژه ای ندارید، برای پذیرش شرایط خدمات Google APIs، این صفحه را می بینید:
هنگامی که شرایط را پذیرفتید، پروژه جدیدی به نام " پروژه من " ایجاد می شود و Drive API به طور خودکار فعال می شود. 3. اگر در عوض، قبلاً یک پروژه ایجاد کرده باشید (شاید کد قبلی خود را؟)، در عوض این صفحه را دریافت خواهید کرد:
هنگامی که بر روی گزینه Create a project کلیک می کنید، یک پروژه موجود را انتخاب کنید یا واقعاً یک پروژه جدید ایجاد کنید.
هنگامی که انتخاب خود را انجام دادید (پروژه جدید یا موجود)، Drive API به طور خودکار برای شما فعال می شود. 4. میدانید که Drive API با این تأیید فعال شده است:
5. برای رفتن به مرحله بعد روی Go to credentials کلیک کنید.
7. * مجوز درخواست های API (مجوز کاربر)
اگر قبلاً اعتبارنامه مجوز حساب کاربری را ایجاد کرده باشید و با این فرآیند آشنایی داشته باشید، میتوانید این بخش را نادیده بگیرید. این با مجوز حساب سرویس که تکنیک آن متفاوت است متفاوت است، بنابراین لطفاً در زیر ادامه دهید.
مقدمه ای برای مجوز (به علاوه برخی از احراز هویت)
برای ارسال درخواست به APIها، برنامه شما باید مجوز مناسب را داشته باشد. احراز هویت ، کلمه ای مشابه، اعتبار ورود به سیستم را توصیف می کند—شما خود را هنگام ورود به حساب Google خود با ورود و رمز عبور احراز هویت می کنید. پس از احراز هویت، مرحله بعدی این است که آیا شما مجاز هستید یا بهتر بگوییم کد شما مجاز به دسترسی به دادههایی مانند فایلهای حباب در فضای ذخیرهسازی ابری یا فایلهای شخصی کاربر در Google Drive هستید.
APIهای Google از چندین نوع مجوز پشتیبانی میکنند، اما رایجترین مورد برای کاربران Google Workspace API مجوز کاربر است، زیرا برنامه نمونه در این آزمایشگاه کد به دادههای متعلق به کاربران نهایی دسترسی دارد. این کاربران نهایی باید به برنامه شما اجازه دسترسی به دادههایشان را بدهند. این بدان معنی است که کد شما باید اعتبار حساب کاربری OAuth2 را دریافت کند.
برای دریافت اعتبار OAuth2 برای مجوز کاربر، به مدیر API برگردید و برگه "Credentials" را در نوار سمت چپ انتخاب کنید:
وقتی به آنجا رسیدید، تمام اطلاعات کاربری خود را در سه بخش مجزا خواهید دید:
اولین مورد برای کلیدهای API ، شناسه های مشتری OAuth 2.0 و آخرین سرویس OAuth2 است — ما از یکی در وسط استفاده می کنیم.
ایجاد اعتبار
از صفحه اعتبار، روی دکمه + ایجاد اعتبارنامه در بالا کلیک کنید، که سپس یک گفتگو به شما می دهد که در آن "OAuth Client ID" را انتخاب کنید:
در صفحه بعدی، 2 عمل دارید: پیکربندی مجوز برنامه خود "صفحه رضایت" و انتخاب نوع برنامه:
اگر صفحه رضایت تنظیم نکرده باشید، اخطار را در کنسول خواهید دید و اکنون باید این کار را انجام دهید. (اگر صفحه رضایت شما قبلاً تنظیم شده است، از این مراحل بعدی رد شوید.)
صفحه رضایت OAuth
روی «پیکربندی صفحه رضایت» کلیک کنید، جایی که یک برنامه «خارجی» (یا «داخلی» اگر مشتری Google Workspace [که قبلا «Google Workspace»] هستید را انتخاب میکنید):
توجه داشته باشید که برای اهداف این تمرین، مهم نیست که کدام را انتخاب میکنید، زیرا نمونه کد کد خود را منتشر نمیکنید. اکثر افراد برای نمایش به صفحه پیچیده تر، "External" را انتخاب می کنند، اما شما در واقع فقط باید قسمت "Application name" را در بالا تکمیل کنید:
تنها چیزی که در حال حاضر به آن نیاز دارید فقط یک نام برنامه است، بنابراین فردی را انتخاب کنید که نشان دهنده کدهای شما باشد و سپس روی ذخیره کلیک کنید.
ایجاد شناسه مشتری OAuth (user acct auth)
اکنون برای ایجاد شناسه مشتری OAuth2 به برگه Credentials برگردید. در اینجا انواع شناسه های مشتری OAuth را می بینید که می توانید ایجاد کنید:
ما در حال توسعه یک ابزار خط فرمان هستیم که عبارت Other است، بنابراین آن را انتخاب کنید و سپس روی دکمه ایجاد کلیک کنید. یک نام شناسه مشتری که منعکس کننده برنامه ای است که ایجاد می کنید انتخاب کنید یا به سادگی نام پیش فرض را انتخاب کنید، که معمولاً «کلینت دیگر N » است.
در حال ذخیره اعتبار شما
- یک گفتگو با اعتبارنامه جدید ظاهر می شود. روی OK کلیک کنید تا بسته شود
- در صفحه اعتبارنامه ها، به بخش «شناسه های مشتری OAuth2» بروید و روی نماد دانلود کلیک کنید.
در انتهای سمت راست شناسه مشتری تازه ایجاد شده شما.
- این یک گفتگو برای ذخیره فایلی با نام
client_secret-
LONG-HASH-STRING
.apps.googleusercontent.com.json
باز می کند که احتمالاً در پوشه دانلودهای شما. ما توصیه میکنیم به نام سادهتری مانندclient_secret.json
(که همان چیزی است که برنامه نمونه استفاده میکند) کوتاه کنید، سپس آن را در فهرست/پوشهای ذخیره کنید که در آن برنامه نمونه را در این Codelab ایجاد میکنید.
خلاصه
با در دست داشتن اطلاعات کاربری، اکنون آماده دسترسی به Drive API از برنامه خود هستید، هدف از شناسه مشتری OAuth این است که کاربران شما باید به برنامه شما اجازه دسترسی به داده های خود در Google Drive را بدهند.
توجه : جزئیات بیشتر در مورد ایجاد پروژهها، فعال کردن APIها، و دریافت اعتبار، به صورت دستی، یعنی بدون استفاده از "جادوگر" بالا، پس از پایان این آزمایشگاه کد برای مطالعه بیشتر در دسترس است.
8. نمایش برنامه فایلها و پوشههای Drive شما
چه در محیط توسعه محلی خود یا در Cloud Shell، در همان دایرکتوری که فایل اعتبار client_id.json
شما قرار دارد، یک فایل Python جدید با نام 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'])
ساختار برنامه
سه بخش اصلی برای این برنامه وجود دارد:
- پایتون برای وارد کردن عملکرد کتابخانه وارد می شود
- اخذ اعتبار درخواست
- واکشی نام فایل و پوشه و انواع MIME در Google Drive و نمایشگر کاربر
توجه : بررسی عمیقتر کد و مرور یک توضیح خط به خط پس از پایان این آزمایشگاه کد برای مطالعه بیشتر در دسترس است.
در حال اجرای برنامه
نام این فایل را چیزی شبیه 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
اگر توجه نمی کردید و برنامه را در 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 و انواع MIME آن ها مشاهده شود. در اینجا یک مثال از یکی از حساب های آزمایشی ما آورده شده است:
$ 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 ذخیره شده است)، و مستقیماً به خروجی می روید. آیا دیدن اسناد خود در ترمینال برای اولین بار هیجان انگیز نیست؟ ما اینطور فکر می کنیم!
9. نتیجه گیری
اکنون آمادهاید تا ویژگیهای بیشتری درباره Drive API بیاموزید یا سایر Google Workspace (Gmail، Google Docs، Sheets، Slides، Calendar) و سایر APIهای Google (Maps، Analytics، YouTube و غیره) را کاوش کنید. تبریک می گویم که این کار را تا انتها انجام دادید!
کدهای ارائه شده در این Codelab نیز در مخزن GitHub آن در github.com/googlecodelabs/gsuite-apis-intro موجود است. (هدف ما این است که این نرم افزار کد را با مخزن همگام نگه داریم.) آیا برای ادامه کار آماده هستید؟ در زیر منابع مختلفی وجود دارد که میتوانید به آنها دسترسی داشته باشید تا به شما کمک کنند تا بیشتر در مورد مطالبی که در این کد لبه پوشش داده شده است کاوش کنید، یا اگر میخواهید ذهن خود را توسعه دهید و راههای دیگر دسترسی برنامهریزی به فناوریهای Google را کشف کنید.
همانطور که قبلاً اشاره شد، اگر یک توسعهدهنده معمولی پایتون نیستید، از شما دعوت میکنیم که این مثال لبه کد را در زبان توسعه مورد علاقه خود دوباره انجام دهید. کتابخانه های مشتری برای زبان های پشتیبانی شده در اینجا موجود است.
مطالعه تکمیلی
اکنون که تجربه ای با Drive API دارید، در زیر چند تمرین توصیه شده برای توسعه بیشتر مهارت های خود آورده شده است:
- فایلهای ZIP : برنامهای بنویسید که از چندین بایگانی ZIP در Drive پشتیبانگیری میکند، و آنها را بلافاصله از حالت فشرده خارج میکند تا نام هر فایل ZIP، نام پوشهای باشد که آن فایلها در آن قرار میگیرند. اعتبار اضافی: بایگانی های ZIP بازگشتی را در فایل های ZIP دیگر با پوشه های Drive که در داخل پوشه های دیگر تعبیه شده است، پشتیبانی می کند. اگر تسلیم شدید، این برنامه نمونه Node.js را ببینید.
- آلبومهای عکس : شروع یک ابزار تولید آلبوم عکس را بنویسید که چندین تصویر را در Google Drive آپلود میکند و آنها را در پوشههای جداگانه بر اساس مهر زمانی و موقعیت جغرافیایی سازماندهی میکند. اعتبار اضافی: یک کتابخانه دستکاری تصویر منبع باز پیدا کنید و همه عکسها را در هر پوشه بچینید تا رویدادهایی را که ممکن است تجربه کرده باشید (یک سفر، یک شام و غیره) نشان دهید.
- کاوش GCP : برنامهای بنویسید که Google Workspace و Google Cloud Platform (GCP) را به یکدیگر متصل کند. ابزاری بنویسید که از فایلهای تصویری Google Drive در Google Cloud Storage (GCS) که راهحل دیگری برای «ذخیرهسازی فایل در ابر» است، پشتیبانگیری کند. باور کنید یا نه، استفاده از GCS به دلیل کتابخانههای مشتری پیشرفتهاش، سادهتر از Drive خواهد بود.
- تجزیه و تحلیل و ضبط : راه حل خود را با تجزیه و تحلیل هر تصویر پشتیبانگیری شده با ارسال آن به Google Cloud Vision API و گرفتن «برچسبهای» بالای (3، 5، 10) از آنچه API در آن تصاویر میبیند، به شماره 3 گسترش دهید. برای هر تصویر، یک ردیف در Google Sheet بنویسید که حاوی تجزیه و تحلیل از Cloud Vision و همچنین مکان پشتیبانگیری شده آن در GCS است. اگر تسلیم شدید، این کد زبان پایتون را ببینید.
10. منابع اضافی
مستندات
- اسناد Google Drive API (REST API و SDK/API بومی Android)
- سایر اسناد APIهای Google Workspace
- سایر اسناد Google APIs
- کتابخانه های سرویس گیرنده Google APIs
- اسناد OAuth2
ویدیوهای مرتبط و کلی
- ایجاد پروژه های Google API جدید ( پست وبلاگ و ویدیو )
- بررسی کد دیگ بخار مجوز پایتون ( ویدئو )
- فهرست کردن فایلهای خود در Google Drive ( ویدئو ، پست وبلاگ )
- کتابخانه ویدیوی Google Drive API
- سری ویدیوهای Launchpad Online (سلف ...)
- مجموعه ویدیوهای Google Workspace Dev Show
اخبار و به روز رسانی
- وبلاگ توسعه دهندگان Google Workspace
- توسعه دهندگان Google Workspace Twitter (@GSuiteDevs)
- خبرنامه ماهانه توسعه دهندگان Google Workspace
سایر کدها
مقدماتی
- [Apps Script] مقدمه Google Apps Script
متوسط
- [Apps Script] ابزار خط فرمان CLASP Apps Script
- [Apps Script] افزونههای Gmail
- [Apps Script] Docs Add-on & GCP Natural Language API
- [Apps Script] چارچوب ربات Hangouts Chat
- [REST APIs] ابزار گزارش سفارشی (Sheets API)
- [REST APIs] تولید کننده اسلاید سفارشی برای تحلیلگر BigQuery مجوز Github (Slides+BigQuery API)
پیشرفته
- [REST APIs] گردش کار پردازش تصویر Cloud (Drive، Cloud Storage، Cloud Vision، Sheets API)
برنامه های مرجع
- مبدل علامت گذاری به اسلایدهای Google (Slides REST API)
11. *توضیحات جزئی برنامه
این بخش اختیاری قرار است پس از پایان جلسه به عنوان خود مطالعه برای پر کردن شکاف هایی که ممکن است ایجاد شده باشد یا برای تحقیقات بیشتر استفاده شود.
پایتون برای وارد کردن عملکرد کتابخانه وارد می شود
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
- اولین دستور
import
این کد را قادر میسازد تا در پایتون 2 اجرا شود - اگر فقط از پایتون 3 استفاده میکنید، میتوان آن را به طور کامل حذف کرد. - یکی از دستورالعملهای سبک پایتون این است که کتابخانه استاندارد و واردات ماژول شخص ثالث را از هم جدا کنید - خط خالی برای همین است.
- سه واردات بعدی، کلاسها و عملکردهای لازم را از کتابخانه سرویس گیرنده Google APIs وارد میکنند... همه برای نوشتن این برنامه مورد نیاز ما هستند. به طور خلاصه، کارهایی که آنها انجام می دهند به شرح زیر است:
-
googleapiclient
بر اتصال به APIهای Google تمرکز دارد -
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'
- برای برقراری ارتباط برنامهها با سرورهای Google، یک رمز لازم است. نشانههای معتبری که از Google برمیگردند در فایل ذخیرهسازی رمز ذخیره میشوند،
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)
- هنگامی که برنامه شما یک جریان داشته باشد، باید اجرا شود تا صفحه مجوزهای OAuth2 به کاربر ارائه شود [از طریق
oauth2client.tools.run_flow()
] که در بالا توضیح داده شده و نشان داده شده است.
creds = tools.run_flow(flow, store)
- با کلیک کردن روی اجازه ، کاربران با دسترسی برنامه شما به فراداده فایل Google Drive خود موافقت میکنند و سرورهای Google برای دسترسی به API نشانههایی را برمیگردانند. آنها به عنوان
creds
برگردانده شده و در فایلstorage.json
ذخیره می شوند. - در این مرحله، برنامه شما اکنون دارای اعتبارنامه های معتبر برای برقراری تماس های API است. فراخوانی
googleapiclient.discovery.build()
یک نقطه پایانی سرویس برای API مورد استفاده شما ایجاد می کند. - برای استفاده از
build()
نام API ('drive'
) و نسخه مورد نظر (در حال حاضر'v3'
) را وارد کنید. - پارامتر نهایی یک سرویس گیرنده HTTP است که برای تماس های API رمزگذاری شده استفاده می شود.
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
واکشی و نمایش 100 فایل/پوشه و نوع MIME اول Drive)
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
- خط بعدی کد متد
list()
در مجموعهfiles()
را برای Drive API فراخوانی می کند تا درخواست را بسازد که بلافاصله باexecute()
فراخوانی می شود. یکdict
Python برگردانده میشود که از آن کلید'files'
را میخواهیم تا نام ۱۰۰ فایل و پوشه را از Google Drive کاربر دریافت کنیم (یا کمتر اگر فایلهای کمتری دارید). - چرا 100؟ این پیشفرض از
DRIVE.files().list()
است. اگر میخواهید این عدد را تغییر دهید، مثلاً به 10 فایل یا 1000 فایل، پارامترpageSize
را به درخواست خود اضافه کنید:DRIVE.files().list(pageSize=10)
. در اینجا اسناد برای گزینه های بیشتر است. - بخش پایانی اسکریپت در میان هر فایل حلقه می زند و نام و نوع فایل MIME را نمایش می دهد.
شما اکنون اولین برنامه خود را نوشته اید که از API Google REST استفاده می کند... تبریک می گوییم! جدا از کد واردات و مجوز، این اسکریپت واقعاً فقط چند خط کد است (آنچه در بالا می بینید). اکثر API های Google به روشی مشابه کار می کنند و شما فقط باید برای هر کدام که می خواهید استفاده کنید، نقطه پایانی سرویس ایجاد کنید.
استفاده از بیش از یک Google API در یک برنامه
بله، مطمئناً می توانید از بیش از یک API در یک برنامه استفاده کنید! در اینجا یک قطعه کد Python برای برنامهای است که از همان سرویس گیرنده HTTP استفاده مجدد میکند و نقاط پایانی سرویس را برای سه API Google ایجاد میکند (بله، همچنین با 3 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)
تصور میکنیم این کد میتواند بخشی از برنامهای باشد که بر اساس دادههای صفحهگسترده (Sheets API) چند عرشه اسلاید (Slides API) تولید میکند و از یک الگوی اسلاید استفاده میکند که برای هر دسته تولید شده کپی میشود (Drive API). در حالی که چنین برنامه ای وجود ندارد، شما باید بتوانید با استفاده از دو نمونه موجود که تیم Google Workspace به عنوان بلوک های سازنده ایجاد کرده است، چیزی مشابه بسازید:
- جایگزینی متن و تصاویر در اسلایدها ( پست وبلاگ و ویدیو ) - از Drive API برای کپی کردن یک قالب اسلاید استفاده میکند و سپس از Slides API برای تغییر متغیرهای متن و تصویر استفاده میکند.
- تولید اسلاید از دادههای صفحهگسترده ( پست وبلاگ و ویدیو ) - دادهها را از صفحهگسترده (Sheets API) میخواند و بر اساس آن دادهها اسلایدها (Slides API) ایجاد میکند.
چالش شما: آن برنامه را بسازید!
12. * استفاده پیشرفته از devconsole
در این بخش اختیاری، نحوه ایجاد پروژهها در devconsole، فعال کردن APIها و دریافت اعتبار، همه بدون استفاده از جادوگر مانند بالا در Codelab را شرح میدهیم. این برای کاربران متوسط است که به اندازه کافی راحت هستند که آن را به صورت دستی انجام دهند یا مایلند یاد بگیرند که چگونه این کار را انجام دهند.
پروژه را در کنسول Cloud مشخص کنید
هر زمان که برنامه ای را با استفاده از Google API می نویسید، باید یک پروژه داشته باشید. می توانید از یک پروژه موجود مجددا استفاده کنید یا یک پروژه جدید ایجاد کنید. این در Cloud Console اتفاق می افتد. برخی از لبههای کد یک پیوند جادویی (مانند یک جادوگر راهاندازی) ارائه میکنند که شما را به سرعت پیش میبرد و بسیاری از مراحل مورد نیاز را نادیده میگیرد. اما همه آنها این کار را نمی کنند، بنابراین اینها دستورالعمل های کلی در مورد نحوه ایجاد پروژه ها هستند.
میتوانید پروژهها را از اکثر صفحههای موجود در کنسول Cloud ایجاد کنید، به شرطی که با اعتبار Google خود وارد شوید و یک پروژه کشویی در بالای کنسول ببینید. توجه داشته باشید که بیشتر اسکرینشاتها در اینجا از API Manager با نام Developers Console گرفته شدهاند (به راحتی با کلیک کردن روی "API manager" در سمت چپ یا اشاره مستقیم مرورگر خود به console.developers.google.com قابل دسترسی است.
- اگر هنوز هیچ پروژه ای ندارید، ممکن است به ...
- صفحه داشبورد :
- صفحه کتابخانه :
- یا یک صفحه کاملاً خالی:
اگر سومین مورد برای شما اتفاق افتاد، فقط مرورگر را رفرش کنید تا به صفحه کتابخانه منتقل شوید.
- چه در صفحات داشبورد یا کتابخانه باشید، روی انتخابگر پروژه در بالای صفحه کلیک کنید:
- در مرحله بعد، کادر گفتگوی انتخابگر را دریافت خواهید کرد. برای ایجاد یک پروژه جدید روی "+" در سمت راست کلیک کنید:
- پس از کلیک بر روی "+" ، یک صفحه پروژه جدید ظاهر می شود. کلیه حساب های مصرف کننده به طور پیش فرض 12 پروژه دریافت می کنند. قبل از ایجاد اولین پروژه خود ، باید شرایط خدمات Google API را بپذیرید:
پس از انجام این کار ، هنگام ایجاد پروژه های آینده ، درخواست ایمیل و شرایط سؤالات خدمات از بین می رود:
5- اگر در گذشته حداقل یک پروژه ایجاد کرده اید ، پس از ورود به سیستم ، به داشبورد آخرین پروژه ای که روی آن کار کرده اید منتقل می شوید. از آنجا ، یک پروژه جدید ایجاد کنید زیرا می خواهید یک پروژه را انتخاب کنید > + . 6. پس از ایجاد پروژه جدید خود ، در صفحه داشبورد باز خواهید گشت:
اکنون یک پروژه را با موفقیت ایجاد کرده اید و با انتخاب API هایی که می خواهید برای پروژه خود استفاده کنید ، آماده حرکت هستید.
API های Google را فعال کنید
قبل از شروع استفاده از Google API ، باید آنها را فعال کنید. مثال زیر نشان می دهد که شما برای فعال کردن API Cloud Vision چه کاری انجام می دهید. در این CodeLab ، شما ممکن است از یک یا چند API استفاده کنید ، و باید مراحل مشابهی را دنبال کنید تا قبل از استفاده آنها را فعال کنید.
از Cloud Shell
با استفاده از پوسته ابر ، می توانید API را با استفاده از دستور زیر فعال کنید:
gcloud services enable vision.googleapis.com
از کنسول Cloud
همچنین ممکن است API Vision را در مدیر API فعال کنید. از کنسول ابر ، به API Manager بروید و "کتابخانه" را انتخاب کنید.
در نوار جستجو ، شروع به تایپ کردن ، "Vision" ، سپس Vision API را هنگام ظاهر شدن انتخاب کنید. ممکن است در حال تایپ چیزی شبیه به این باشد:
Cloud Vision API را انتخاب کنید تا دیالوگ را که در زیر مشاهده می کنید دریافت کنید ، سپس بر روی دکمه "Enable" کلیک کنید:
هزینه
در حالی که بسیاری از API های Google بدون هزینه قابل استفاده هستند ، استفاده از GCP (محصولات و API) رایگان نیست. هنگام فعال کردن API VISION (همانطور که در بالا توضیح داده شد) ، ممکن است از شما یک حساب صورتحساب فعال خواسته شود. اطلاعات قیمت گذاری API Vision باید قبل از فعال کردن توسط کاربر ارجاع شود. به خاطر داشته باشید که برخی از محصولات Google Cloud Platform (GCP) دارای یک ردیف "همیشه رایگان" هستند که برای تحمل صورتحساب باید از آن فراتر بروید. برای اهداف CodeLab ، هر تماس به API Vision در برابر آن ردیف آزاد شمارش می شود ، و تا زمانی که در کل آن در کل (در هر ماه) در محدوده آن بمانید ، نباید هیچ هزینه ای متحمل شوید.
برخی از API های Google ، IE ، Google Workspace ، استفاده از اشتراک ماهانه را تحت پوشش قرار می دهد ، بنابراین هیچ صورتحساب مستقیم برای استفاده از Gmail ، Google Drive ، تقویم ، اسناد ، برگه ها و API های اسلایدها وجود ندارد. صورتحساب محصولات مختلف Google متفاوت است، بنابراین حتماً برای این اطلاعات به اسناد API خود مراجعه کنید.
خلاصه
در این CodeLab ، شما فقط باید API Google Drive را روشن کنید ، بنابراین دستورالعمل های بالا را دنبال کرده و "درایو" را جستجو کنید. پس از فعال شدن ، به جلو بروید.
مجوز درخواست های API (مجوز کاربر)
معرفی مجوز (به علاوه برخی احراز هویت)
به منظور درخواست درخواست به API ها ، درخواست شما باید مجوز مناسب داشته باشد. احراز هویت ، یک کلمه مشابه ، اعتبار ورود به سیستم را توصیف می کند - هنگام ورود به حساب Google خود با ورود به سیستم و رمز عبور ، خود را تأیید می کنید. پس از تأیید اعتبار ، مرحله بعدی این است که آیا شما هستید یا نه ، کد شما مجاز به دسترسی به داده ها مانند پرونده های Blob در ذخیره سازی ابر یا پرونده های شخصی کاربر در Google Drive است.
Google API ها از انواع مختلفی از مجوز پشتیبانی می کنند ، اما یکی از رایج ترین آنها برای کاربران API Google Workspace مجوز کاربر است زیرا برنامه مثال در این CodeLab به داده های متعلق به کاربران نهایی دسترسی دارد. این کاربران نهایی برای دسترسی به داده های خود باید به برنامه شما اجازه اعطا کنند. این بدان معنی است که کد شما باید اعتبار کاربر OAUTH2 را بدست آورد.
برای دریافت اعتبار OAUTH2 برای مجوز کاربر ، به مدیر API برگردید و برگه "اعتبارنامه" را در سمت چپ انتخاب کنید:
وقتی به آنجا رسیدید ، تمام اعتبار خود را در سه بخش جداگانه مشاهده خواهید کرد:
اولین مورد برای API Keys ، دومین شناسه مشتری OAUTH 2.0 و آخرین سرویس OAUTH2 است که ما از یک وسط استفاده می کنیم.
ایجاد اعتبار
از صفحه Credentials ، روی دکمه + ایجاد اعتبار در بالای صفحه کلیک کنید ، که سپس به شما گفتگو می دهد که در آن می خواهید "شناسه مشتری OAUTH را انتخاب کنید:"
در صفحه بعدی ، شما 2 عمل دارید: پیکربندی مجوز برنامه خود "صفحه رضایت" و انتخاب نوع برنامه:
اگر صفحه رضایت را تنظیم نکرده اید ، هشدار در کنسول را مشاهده خواهید کرد و اکنون باید این کار را انجام دهید. (اگر صفحه رضایت شما از قبل تنظیم شده است ، این مراحل بعدی را پرش کنید.)
صفحه رضایت OAUTH
روی "پیکربندی صفحه رضایت" کلیک کنید که اگر یک مشتری Google Workspace هستید) برنامه "خارجی" (یا "داخلی" را انتخاب می کنید):
توجه داشته باشید که برای اهداف این تمرین ، فرقی نمی کند که انتخاب کنید زیرا نمونه CodeLab خود را منتشر نمی کنید. بیشتر افراد "خارجی" را انتخاب می کنند تا به یک صفحه نمایش پیچیده تر منتقل شوند ، اما شما واقعاً فقط باید قسمت "نام برنامه" را در بالا تکمیل کنید:
تنها چیزی که در این زمان به آن نیاز دارید فقط یک نام برنامه است ، بنابراین شخصی را انتخاب کنید که منعکس کننده CodeLab شما باشد و سپس روی ذخیره کلیک کنید.
ایجاد شناسه مشتری OAUTH (کاربر acct auth)
اکنون برای ایجاد شناسه مشتری OAUTH2 به برگه Credentials برگردید. در اینجا انواع شناسه مشتری OAuth را می توانید ایجاد کنید:
ما در حال تهیه یک ابزار خط فرمان هستیم که دیگر است ، بنابراین آن را انتخاب کنید و سپس روی دکمه ایجاد کلیک کنید. نام شناسه مشتری را که بازتاب برنامه ای را که ایجاد می کنید انتخاب کنید یا نام پیش فرض را که معمولاً "مشتری دیگر N " است ، انتخاب کنید.
صرفه جویی در اعتبار خود
- گفتگوی با اعتبار جدید ظاهر می شود. برای بستن روی OK کلیک کنید
- به صفحه اعتبارنامه برگردید ، به قسمت "IDS مشتری OAUTH2" بروید و روی نماد بارگیری کلیک کنید
به پایین سمت راست شناسه مشتری تازه ایجاد شده خود.
- این یک گفتگو برای ذخیره پرونده ای به نام
client_secret-
LONG-HASH-STRING
.apps.googleusercontent.com.json
، احتمالاً برای پوشه بارگیری شما باز می شود. توصیه می کنیم به یک نام ساده تر مانندclient_secret.json
(که برنامه نمونه از آن استفاده می کند) کوتاه کنید ، سپس آن را در فهرست/پوشه ذخیره کنید که در آن می توانید برنامه نمونه را در این CodeLab ایجاد کنید.