מסמך זה מספק את כל המידע הבסיסי הנדרש כדי להתחיל להשתמש בספרייה. הוא עוסק במושגים של הספרייה, שמציג דוגמאות לתרחישים שונים לדוגמה, ומספק קישורים למידע נוסף.
הגדרה
יש כמה פעולות הגדרה שצריך לבצע כדי להשתמש בספרייה הזו:
- אם עדיין אין לך חשבון Google: להרשמה.
- אם אף פעם לא יצרת פרויקט ב-Google API Console, עליך לקרוא את הדף 'ניהול פרויקטים' וליצור פרויקט מסוף Google API.
- מתקינים את חבילת NuGet שרוצים לעבוד איתה.
אימות והרשאה
חשוב להבין את העקרונות הבסיסיים של טיפול באימות ובהרשאה של API. כל הקריאות ל-API צריכות לכלול גישה פשוטה או גישה מורשית (מוגדרת בהמשך). יש הרבה שיטות API שדורשות גישה מורשית, אבל חלקן יכולות להשתמש בכל אחת מהן. יש כמה שיטות API שיכולות להשתמש בכל אחת מהן באופן שונה, בהתאם לשימוש בגישה פשוטה או בגישה מורשית. כדי לקבוע את סוג הגישה המתאים, אפשר לעיין במסמכי התיעוד של ה-API.
1. גישה פשוטה ל-API (מפתחות API)
לקריאות האלה ל-API אין גישה לנתונים פרטיים של משתמשים. האפליקציה צריכה לאמת את עצמה כאפליקציה ששייכת לפרויקט שלכם ב'מסוף Google API'. השלב הזה נדרש כדי למדוד את השימוש בפרויקט למטרות חשבונאות.
API key: כדי לאמת את האפליקציה, צריך להשתמש מפתח API לפרויקט שלך במסוף API. כל בקשת גישה פשוטה שהאפליקציה שלכם מבצעת חייבת לכלול את המפתח הזה.
2. גישה מורשית ל-API (OAuth 2.0)
הקריאות האלה ל-API ניגשות לנתונים פרטיים של משתמשים. לפני שאפשר להתקשר אליהם, המשתמש שיש לו גישה למידע הפרטי חייב להעניק לאפליקציה גישה. לכן צריך לאמת את האפליקציה שלכם, המשתמש חייב להעניק גישה לאפליקציה, ועל המשתמש לעבור אימות כדי להעניק את הגישה. את כל זה אפשר להשיג באמצעות OAuth 2.0 וספריות שנכתבו עבורו.
היקף: בכל API מוגדר היקף אחד או יותר שבו מצהירים על קבוצת פעולות המותרות. לדוגמה, ל-API יכולות להיות היקפים לקריאה בלבד ולקריאה-כתיבה. כשהאפליקציה מבקשת גישה לנתוני משתמשים, הבקשה חייבת לכלול היקף אחד או יותר. המשתמש צריך לאשר את היקף הגישה שהאפליקציה שלכם מבקשת.
אסימוני רענון וגישה: כשמשתמש מעניק לאפליקציה גישה, שרת ההרשאות OAuth 2.0 מספק לאפליקציה אסימוני רענון וגישה. האסימונים האלה תקפים רק להיקף המבוקש. האפליקציה שלך משתמשת באסימוני גישה כדי לאשר קריאות ל-API. התוקף של אסימוני הגישה פג, אבל לאסימוני הרענון אין תאריך תפוגה. האפליקציה שלכם יכולה להשתמש באסימון רענון כדי לקבל אסימון גישה חדש.
Client-ID וסוד לקוח: המחרוזות האלה מזהות את האפליקציה באופן ייחודי ומשמשות להשגת אסימונים. הם נוצרים בשביל הפרויקט במסוף API. יש שלושה סוגים של מזהי לקוח: לכן חשוב לוודא שאתם מקבלים את הסוג המתאים לבקשה שלכם:
- מזהי לקוח של אפליקציית אינטרנט
- מזהי לקוח של אפליקציה מותקנת
- מספרי לקוח בחשבונות שירות
דוגמאות
בקטע הזה מוצגות דוגמאות לשימוש פשוט ב-API ללא הרשאה. למידע נוסף על קריאות הרשאה, אפשר לעיין במאמר דף OAuth 2.0 ל- .NET.
דוגמה ל-API פשוט
בדוגמה הזו נעשה שימוש בגישה פשוטה באמצעות API לאפליקציה של שורת הפקודה. היא קוראת ל- Google Discovery API כדי להציג את רשימת כל ממשקי ה-API של Google.
הגדרה לדוגמה
מקבלים מפתח API פשוט. כדי למצוא את מפתח ה-API של האפליקציה:
- פותחים את הדף Credentials במסוף ה-API.
-
ה-API הזה תומך בשני סוגים של פרטי כניסה.
יוצרים את פרטי הכניסה שמתאימים לפרויקט:
-
OAuth 2.0: בכל פעם שהאפליקציה שלכם מבקשת משתמש פרטי נתונים, עליו לשלוח אסימון OAuth 2.0 יחד עם הבקשה. שלך תחילה שולח מזהה לקוח, ואולי גם סוד לקוח, לקבל אסימון. אפשר ליצור פרטי כניסה של OAuth 2.0 לאינטרנט אפליקציות, חשבונות שירות או אפליקציות מותקנות.
מידע נוסף זמין במסמכי התיעוד של OAuth 2.0.
-
מפתחות API: בקשה שלא מספקת אסימון OAuth 2.0 חייבת לשלוח API מקש. המפתח מזהה את הפרויקט ומספק גישה ל-API, מכסה דוחות.
ה-API תומך בכמה סוגים של הגבלות על מפתחות API. אם מפתח ה-API אין צורך שיהיה קיים, יש ליצור מפתח API במסוף באמצעות לחיצה על יצירת פרטי כניסה > מפתח API. אפשר להגביל את המפתח לפני שמשתמשים בו בסביבת הייצור, לוחצים על Restrict key ובוחרים הגבלות.
-
כדי להגן על מפתחות ה-API, צריך לפעול לפי השיטות המומלצות באמצעות מפתחות API באופן מאובטח.
קוד לדוגמה
using System; using System.Threading.Tasks; using Google.Apis.Discovery.v1; using Google.Apis.Discovery.v1.Data; using Google.Apis.Services; namespace Discovery.ListAPIs { /// <summary> /// This example uses the discovery API to list all APIs in the discovery repository. /// https://developers.google.com/discovery/v1/using. /// <summary> class Program { [STAThread] static void Main(string[] args) { Console.WriteLine("Discovery API Sample"); Console.WriteLine("===================="); try { new Program().Run().Wait(); } catch (AggregateException ex) { foreach (var e in ex.InnerExceptions) { Console.WriteLine("ERROR: " + e.Message); } } Console.WriteLine("Press any key to continue..."); Console.ReadKey(); } private async Task Run() { // Create the service. var service = new DiscoveryService(new BaseClientService.Initializer { ApplicationName = "Discovery Sample", ApiKey="[YOUR_API_KEY_HERE]", }); // Run the request. Console.WriteLine("Executing a list request..."); var result = await service.Apis.List().ExecuteAsync(); // Display the results. if (result.Items != null) { foreach (DirectoryList.ItemsData api in result.Items) { Console.WriteLine(api.Id + " - " + api.Title); } } } } }
טיפים לשימוש במפתחות API:
- כדי להשתמש בשירות ספציפי, צריך להוסיף לו הפניה. לדוגמה אם רוצים להשתמש Tasks API, עליך להתקין את חבילת NuGet שלה Google.Apis.Tasks.v1.
- כדי ליצור מופע של שירות, פשוט קוראים ל-constructor שלו. מוצרים לדוגמה:
new TasksService(new BaseClientService.Initializer {...});"
- כל השיטות של שירות נמצאות במשאבים נפרדים באובייקט השירות עצמו.
שירות Discovery כולל משאב
Apis
, שמכיל methodList
. כשקוראים לפונקציהservice.Apis.List(..)
, מוחזר אובייקט בקשה שמטרגט את השיטה הזו.
כדי לבצע בקשה, צריך להפעיל את ה-methodExecute()
אוExecuteAsyc()
בבקשה. - מגדירים את מפתח ה-API באמצעות המאפיין
ApiKey
במכונהBaseClientService.Initializer
.
חיפוש מידע על ממשקי ה-API
ממשקי API נתמכים מפורטים כל ממשקי ה-API שניתן לגשת אליהם באמצעות הספרייה הזו, כולל קישורים למסמכי תיעוד.
אפשר גם להשתמש APIs Explorer כדי לדפדף בממשקי API, להציג רשימה של שיטות זמינות ואפילו לנסות קריאות ל-API מהדפדפן.