شروع کنید

این سند تمام اطلاعات اولیه مورد نیاز برای شروع استفاده از کتابخانه را ارائه می دهد. مفاهیم کتابخانه را پوشش می دهد، نمونه هایی را برای موارد استفاده مختلف نشان می دهد، و پیوندهایی به اطلاعات بیشتر ارائه می دهد.

راه اندازی

چند مرحله راه اندازی وجود دارد که باید قبل از استفاده از این کتابخانه انجام دهید:

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 خود استفاده کنید. هر تماس دسترسی ساده ای که برنامه شما برقرار می کند باید شامل این کلید باشد.

2. دسترسی مجاز API (OAuth 2.0)

این فراخوان‌های API به داده‌های کاربر خصوصی دسترسی دارند. قبل از اینکه بتوانید با آنها تماس بگیرید، کاربری که به داده های خصوصی دسترسی دارد باید به برنامه شما اجازه دسترسی بدهد. بنابراین، برنامه شما باید احراز هویت شود، کاربر باید به برنامه شما دسترسی بدهد و کاربر باید احراز هویت شود تا به آن دسترسی اعطا شود. همه اینها با OAuth 2.0 و کتابخانه های نوشته شده برای آن انجام می شود.

محدوده : هر API یک یا چند محدوده تعریف می کند که مجموعه ای از عملیات را مجاز اعلام می کند. به عنوان مثال، یک API ممکن است دامنه‌های فقط خواندنی و خواندنی و نوشتنی داشته باشد. هنگامی که برنامه شما درخواست دسترسی به داده های کاربر می کند، درخواست باید شامل یک یا چند محدوده باشد. کاربر باید دامنه دسترسی درخواستی شما را تأیید کند.

نشانه‌های بازخوانی و دسترسی : وقتی کاربر به برنامه شما دسترسی می‌دهد، سرور مجوز OAuth 2.0 به برنامه شما نشانه‌های تازه‌سازی و دسترسی را ارائه می‌دهد. این توکن ها فقط برای محدوده درخواستی معتبر هستند. برنامه شما از نشانه های دسترسی برای مجاز کردن تماس های API استفاده می کند. توکن‌های دسترسی منقضی می‌شوند، اما توکن‌های تازه‌سازی منقضی نمی‌شوند. برنامه شما می تواند از یک نشانه رفرش برای به دست آوردن یک نشانه دسترسی جدید استفاده کند.

شناسه مشتری و راز مشتری : این رشته ها به طور منحصر به فرد برنامه شما را شناسایی می کنند و برای به دست آوردن توکن ها استفاده می شوند. آنها برای پروژه شما در کنسول API ایجاد شده اند. سه نوع شناسه مشتری وجود دارد، بنابراین مطمئن شوید که نوع صحیح برنامه خود را دریافت کنید:

• شناسه های سرویس گیرنده برنامه وب
• شناسه های سرویس گیرنده برنامه نصب شده
• شناسه های مشتری حساب خدمات

نمونه ها

در این بخش، نمونه هایی از استفاده ساده از API بدون مجوز وجود دارد. برای اطلاعات بیشتر درباره تماس‌های مجوز، به صفحه OAuth 2.0 برای دات‌نت مراجعه کنید.

مثال ساده 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 را نصب کنید.
• برای ایجاد یک نمونه از یک سرویس، فقط سازنده آن را فراخوانی کنید. به عنوان مثال: new TasksService(new BaseClientService.Initializer {...});" .
• تمام متدهای یک سرویس بر روی منابع فردی در خود شیء سرویس قرار دارند. سرویس Discovery یک منبع Apis دارد که حاوی یک متد List است. هنگامی که service.Apis.List(..) را فراخوانی می کنید، یک شی درخواست که این متد را هدف قرار می دهد، برگردانده می شود.
  برای اجرای یک درخواست، متد Execute() یا ExecuteAsyc() را روی یک درخواست فراخوانی کنید.
• کلید API را با استفاده از ویژگی ApiKey در نمونه BaseClientService.Initializer تنظیم کنید.

یافتن اطلاعات در مورد API ها

صفحه API های پشتیبانی شده، همه API هایی را که با استفاده از این کتابخانه قابل دسترسی هستند و همچنین پیوندهایی به اسناد فهرست می کند.

همچنین می‌توانید از APIs Explorer برای مرور APIها، فهرست کردن روش‌های موجود و حتی امتحان تماس‌های API از مرورگر خود استفاده کنید.