שנתחיל?

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

הגדרה

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

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

אימות והרשאה

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

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

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

מפתח API: כדי לאמת את האפליקציה, השתמש במפתח API לפרויקט ב-API Console. כל קריאה פשוטה לגישה שהאפליקציה שלך שולחת חייבת לכלול את המפתח הזה.

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

2. גישת API מורשית (OAuth 2.0)

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

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

אסימוני רענון וגישה: כשמשתמש מעניק גישה לאפליקציה, שרת ההרשאות OAuth 2.0 מספק לאפליקציה אסימוני רענון וגישה. האסימונים האלה תקפים רק להיקף המבוקש. האפליקציה שלך משתמשת באסימוני גישה כדי לאשר קריאות ל-API. התוקף של אסימוני הגישה פג, אבל התוקף של אסימוני הרענון לא פג. האפליקציה שלך יכולה להשתמש באסימון רענון כדי להשיג אסימון גישה חדש.

אזהרה: אפשר לשמור על הפרטיות של אסימוני רענון. אם מישהו משיג את האסימונים שלך, הוא יכול להשתמש בהם כדי לגשת לנתונים של משתמשים פרטיים.

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

• מזהי לקוחות של אפליקציית אינטרנט
• מזהי לקוח באפליקציות מותקנות
• מספר לקוח של חשבון שירות

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

דוגמאות

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

דוגמה לממשק API פשוט

בדוגמה הזו נעשה שימוש בגישה פשוטה ל-API עבור אפליקציית שורת פקודה. היא מפעילה את ה-API של Google Discovery כדי להציג את כל ממשקי ה-API של Google.

הגדרה לדוגמה

לקבלת מפתח API פשוט. כדי למצוא את מפתח ה-API של האפליקציה שלך, יש לבצע את הפעולות הבאות:

1. פותחים את דף פרטי הכניסה ב-API Console.
2. ה-API הזה תומך בשני סוגים של פרטי כניסה. יוצרים את פרטי הכניסה המתאימים לפרויקט:

   • OAuth 2.0: בכל פעם שהאפליקציה שלך מבקשת נתוני משתמש פרטיים, עליה לשלוח אסימון OAuth 2.0 יחד עם הבקשה. האפליקציה שלך שולחת תחילה מזהה לקוח, ואולי גם סוד לקוח כדי לקבל אסימון. יש לך אפשרות ליצור פרטי כניסה של OAuth 2.0 לאפליקציות אינטרנט, לחשבונות שירות או לאפליקציות מותקנות.

     למידע נוסף, יש לעיין בתיעוד של OAuth 2.0.

   • מפתחות API: בקשה שלא מספקת אסימון OAuth 2.0 חייבת לשלוח מפתח API. המפתח מזהה את הפרויקט שלך ומספק גישה ל-API, מכסה ודוחות.

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

כדי לשמור על אבטחת מפתחות ה-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 API Google.Apis.Tasks.v1.
• כדי ליצור מופע של שירות, פשוט מתקשרים לבנאי. לדוגמה: new TasksService(new BaseClientService.Initializer {...});".
• כל השיטות של שירות מסוים ממוקמות במקורות מידע נפרדים על אובייקט השירות עצמו. לשירות Discovery יש משאב Apis, שמכיל שיטת List. כשמתקשרים אל service.Apis.List(..), מוחזר אובייקט בקשה שמטרגט את השיטה הזו.
  כדי לבצע בקשה, יש להתקשר לשיטה Execute() או לExecuteAsyc() בעת הבקשה.
• מגדירים את מפתח ה-API באמצעות המאפיין ApiKey במכונה BaseClientService.Initializer.

איתור מידע על ממשקי ה-API

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

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