מתחילים

מסמך זה מספק את כל המידע הבסיסי הנדרש כדי להתחיל להשתמש בספרייה. הוא עוסק במושגים של הספרייה, שמציג דוגמאות לתרחישים שונים לדוגמה, ומספק קישורים למידע נוסף.

הגדרה

יש כמה פעולות הגדרה שצריך לבצע כדי להשתמש בספרייה הזו:

1. אם עדיין אין לך חשבון Google: להרשמה.
2. אם אף פעם לא יצרת פרויקט ב-Google API Console, עליך לקרוא את הדף 'ניהול פרויקטים' וליצור פרויקט מסוף Google API.
3. מתקינים את חבילת NuGet שרוצים לעבוד איתה.

אימות והרשאה

חשוב להבין את העקרונות הבסיסיים של טיפול באימות ובהרשאה של API. כל הקריאות ל-API צריכות לכלול גישה פשוטה או גישה מורשית (מוגדרת בהמשך). יש הרבה שיטות API שדורשות גישה מורשית, אבל חלקן יכולות להשתמש בכל אחת מהן. יש כמה שיטות API שיכולות להשתמש בכל אחת מהן באופן שונה, בהתאם לשימוש בגישה פשוטה או בגישה מורשית. כדי לקבוע את סוג הגישה המתאים, אפשר לעיין במסמכי התיעוד של ה-API.

1. גישה פשוטה ל-API (מפתחות API)

לקריאות האלה ל-API אין גישה לנתונים פרטיים של משתמשים. האפליקציה צריכה לאמת את עצמה כאפליקציה ששייכת לפרויקט שלכם ב'מסוף Google API'. השלב הזה נדרש כדי למדוד את השימוש בפרויקט למטרות חשבונאות.

API key: כדי לאמת את האפליקציה, צריך להשתמש מפתח API לפרויקט שלך במסוף API. כל בקשת גישה פשוטה שהאפליקציה שלכם מבצעת חייבת לכלול את המפתח הזה.

אזהרה: לשמור על הפרטיות של מפתח ה-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 של האפליקציה:

1. פותחים את הדף Credentials במסוף ה-API.
2. ה-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, שמכיל method List. כשקוראים לפונקציה service.Apis.List(..), מוחזר אובייקט בקשה שמטרגט את השיטה הזו.
  כדי לבצע בקשה, צריך להפעיל את ה-method Execute() או ExecuteAsyc() בבקשה.
• מגדירים את מפתח ה-API באמצעות המאפיין ApiKey במכונה BaseClientService.Initializer.

חיפוש מידע על ממשקי ה-API

ממשקי API נתמכים מפורטים כל ממשקי ה-API שניתן לגשת אליהם באמצעות הספרייה הזו, כולל קישורים למסמכי תיעוד.

אפשר גם להשתמש APIs Explorer כדי לדפדף בממשקי API, להציג רשימה של שיטות זמינות ואפילו לנסות קריאות ל-API מהדפדפן.