שנתחיל?

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

Setup (הגדרה)

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

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

אימות והרשאה

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

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

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

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

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

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

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

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

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

דוגמאות

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

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

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

דוגמה להגדרה

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

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

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

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

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