शुरू करें

इस दस्तावेज़ में वह सारी बुनियादी जानकारी मौजूद है जिसकी ज़रूरत आपको लाइब्रेरी का इस्तेमाल शुरू करने के लिए होती है. इसमें लाइब्रेरी के सिद्धांत और इस्तेमाल के अलग-अलग उदाहरणों के बारे में बताया गया है. साथ ही, ज़्यादा जानकारी देने वाले लिंक भी दिए गए हैं.

सेटअप

इस लाइब्रेरी का इस्तेमाल करने से पहले, आपको सेटअप के कुछ चरण पूरे करने होंगे:

1. अगर आपके पास पहले से कोई Google खाता नहीं है, तो साइन अप करें.
2. अगर आपने कभी Google API (एपीआई) कंसोल प्रोजेक्ट नहीं बनाया है, तो प्रोजेक्ट मैनेज करने वाला पेज पढ़ें और Google API कंसोल में एक प्रोजेक्ट बनाएं.
3. वह NuGet पैकेज इंस्टॉल करें जिसके साथ आपको काम करना है.

पुष्टि करना और अनुमति देना

एपीआई की पुष्टि करने और अनुमति देने की प्रक्रिया को मैनेज करने से जुड़ी बुनियादी बातों को समझना ज़रूरी है. सभी एपीआई कॉल को आसान या आधिकारिक ऐक्सेस (नीचे बताया गया है) का इस्तेमाल करना चाहिए. कई एपीआई तरीकों के लिए अनुमति वाले ऐक्सेस की ज़रूरत होती है, लेकिन कुछ तरीकों को इस्तेमाल कर सकते हैं. एपीआई के कुछ तरीके, इनमें से किसी भी एक तरीके का इस्तेमाल अलग-अलग तरीके से कर सकते हैं. यह इस बात पर निर्भर करता है कि आपने आसान ऐक्सेस का इस्तेमाल किया है या अनुमति के बिना. सही ऐक्सेस टाइप तय करने के लिए, एपीआई में बताए गए तरीके से जुड़े दस्तावेज़ देखें.

1. आसान एपीआई ऐक्सेस (एपीआई कुंजियां)

ये एपीआई कॉल, उपयोगकर्ता के निजी डेटा को ऐक्सेस नहीं करते. आपके ऐप्लिकेशन को खुद की पुष्टि, आपके Google API (एपीआई) कंसोल प्रोजेक्ट से जुड़े ऐप्लिकेशन के तौर पर करनी होगी. अकाउंटिंग के मकसद से प्रोजेक्ट के इस्तेमाल को मेज़र करने के लिए इसकी ज़रूरत होती है.

एपीआई पासकोड: अपने ऐप्लिकेशन की पुष्टि करने के लिए, अपने API Console प्रोजेक्ट के लिए एपीआई पासकोड का इस्तेमाल करें. आपका ऐप्लिकेशन जो भी आसान ऐक्सेस कॉल करता है उसमें यह कुंजी शामिल होनी चाहिए.

2. अधिकृत API ऐक्सेस (OAuth 2.0)

ये एपीआई कॉल, उपयोगकर्ता का निजी डेटा ऐक्सेस करते हैं. इन्हें कॉल करने से पहले, जिस उपयोगकर्ता के पास निजी डेटा का ऐक्सेस है उसे आपको ऐप्लिकेशन का ऐक्सेस देना होगा. इसलिए, आपके ऐप्लिकेशन की पुष्टि होनी चाहिए, उपयोगकर्ता को आपके ऐप्लिकेशन का ऐक्सेस देना चाहिए, और वह ऐक्सेस देने के लिए उपयोगकर्ता की पुष्टि होनी चाहिए. ये सब करने के लिए, OAuth 2.0 और इसके लिए लिखी गई लाइब्रेरी का इस्तेमाल किया गया है.

दायरा: हर एपीआई एक या उससे ज़्यादा स्कोप के बारे में बताता है जो ऐसी कार्रवाइयों के सेट का एलान करते हैं जिनकी अनुमति है. उदाहरण के लिए, किसी एपीआई में रीड-ओनली और रीड-राइट स्कोप हो सकते हैं. जब आपका ऐप्लिकेशन, उपयोगकर्ता के डेटा के ऐक्सेस का अनुरोध करता है, तो अनुरोध में एक या उससे ज़्यादा स्कोप शामिल होने चाहिए. उपयोगकर्ता को आपके ऐप्लिकेशन के ऐक्सेस के दायरे को स्वीकार करने की ज़रूरत होगी.

रीफ़्रेश और ऐक्सेस टोकन: जब कोई उपयोगकर्ता आपके ऐप्लिकेशन का ऐक्सेस देता है, तो OAuth 2.0 ऑथराइज़ेशन सर्वर आपके ऐप्लिकेशन को रीफ़्रेश और ऐक्सेस टोकन देता है. ये टोकन सिर्फ़ अनुरोध किए गए दायरे के लिए मान्य हैं. एपीआई कॉल को अनुमति देने के लिए, आपका ऐप्लिकेशन ऐक्सेस टोकन इस्तेमाल करता है. ऐक्सेस टोकन की समयसीमा खत्म हो जाती है, लेकिन रीफ़्रेश टोकन की समयसीमा खत्म नहीं होती. आपका ऐप्लिकेशन, नया ऐक्सेस टोकन पाने के लिए रीफ़्रेश टोकन का इस्तेमाल कर सकता है.

क्लाइंट आईडी और क्लाइंट सीक्रेट: ये स्ट्रिंग खास तरीके से आपके ऐप्लिकेशन की पहचान करती हैं. इनका इस्तेमाल टोकन पाने के लिए किया जाता है. इन्हें एपीआई कंसोल पर आपके प्रोजेक्ट के लिए बनाया गया है. क्लाइंट आईडी तीन तरह के होते हैं. इसलिए, पक्का करें कि आप अपने आवेदन के लिए सही टाइप का इस्तेमाल करें:

• वेब ऐप्लिकेशन क्लाइंट आईडी
• इंस्टॉल किए गए ऐप्लिकेशन क्लाइंट आईडी
• सेवा खाते के क्लाइंट आईडी

उदाहरण

इस सेक्शन में, बिना अनुमति के एपीआई को आसानी से इस्तेमाल करने के उदाहरण दिए गए हैं. अनुमति वाले कॉल के बारे में ज़्यादा जानकारी के लिए, .NET के लिए OAuth 2 .0 पेज देखें.

एपीआई का आसान उदाहरण

इस उदाहरण में, कमांड-लाइन ऐप्लिकेशन के लिए आसान एपीआई ऐक्सेस का इस्तेमाल किया गया है. यह सभी Google एपीआई की सूची बनाने के लिए, Google Discovery API को कॉल करता है.

उदाहरण के लिए सेटअप

अपनी सिंपल एपीआई पासकोड पाएं. अपने ऐप्लिकेशन की API कुंजी ढूंढने के लिए, ये काम करें:

1. एपीआई कंसोल में क्रेडेंशियल पेज खोलें.
2. यह एपीआई दो तरह के क्रेडेंशियल के साथ काम करता है. अपने प्रोजेक्ट के लिए सही क्रेडेंशियल बनाएं:

   • OAuth 2.0: जब भी आपका ऐप्लिकेशन, उपयोगकर्ता के निजी डेटा का अनुरोध करता है, तो उसे अनुरोध के साथ-साथ OAuth 2.0 टोकन भेजना होता है. आपका ऐप्लिकेशन सबसे पहले, एक क्लाइंट आईडी भेजता है. हो सकता है कि टोकन पाने के लिए, आपका क्लाइंट सीक्रेट भेजा गया हो. वेब ऐप्लिकेशन, सेवा खातों या इंस्टॉल किए गए ऐप्लिकेशन के लिए, OAuth 2.0 क्रेडेंशियल जनरेट किए जा सकते हैं.

     ज़्यादा जानकारी के लिए, OAuth 2.0 दस्तावेज़ देखें.

   • एपीआई पासकोड: OAuth 2.0 टोकन न देने वाले अनुरोध के लिए, एपीआई पासकोड भेजना ज़रूरी है. यह कुंजी आपके प्रोजेक्ट की पहचान करती है. साथ ही, एपीआई ऐक्सेस, कोटा, और रिपोर्ट उपलब्ध कराती है.

     एपीआई, एपीआई कुंजियों पर कई तरह की पाबंदियां काम करती है. अगर वह एपीआई पासकोड पहले से मौजूद नहीं है जिसकी आपको ज़रूरत है, तो कंसोल में जाकर क्रेडेंशियल बनाएं > एपीआई पासकोड पर क्लिक करके, एक एपीआई पासकोड बनाएं. प्रोडक्शन में इस्तेमाल करने से पहले, आपके पास कुंजी पर पाबंदी लगाने का विकल्प होता है. इसके लिए, कुंजी पर पाबंदी लगाएं पर क्लिक करें और पाबंदियां में से किसी एक को चुनें.

अपनी एपीआई कुंजियों को सुरक्षित रखने के लिए, एपीआई पासकोड को सुरक्षित तरीके से इस्तेमाल करने के सबसे सही तरीके अपनाएं.

उदाहरण के लिए,

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);
                }
            }
        }
    }
}

एपीआई कुंजियों का इस्तेमाल करने के बारे में सलाह:

• किसी खास सेवा का इस्तेमाल करने के लिए, आपको उसमें एक रेफ़रंस जोड़ना होगा. उदाहरण के लिए, अगर आपको Tasks API का इस्तेमाल करना है, तो आपको इसका NuGet पैकेज इंस्टॉल करना चाहिए Google.Apis.Tasks.v1.
• किसी सेवा का इंस्टेंस बनाने के लिए, बस इसके कंस्ट्रक्टर को कॉल करें. उदाहरण के लिए: new TasksService(new BaseClientService.Initializer {...});".
• सेवा के सभी तरीके, सेवा ऑब्जेक्ट पर ही अलग-अलग संसाधनों पर मौजूद होते हैं. डिस्कवरी सेवा के पास एक Apis रिसॉर्स होता है, जिसमें List तरीका शामिल होता है. service.Apis.List(..) को कॉल करने पर, इस तरीके को टारगेट करने वाला एक अनुरोध ऑब्जेक्ट दिखता है.
  किसी अनुरोध पर कार्रवाई करने के लिए, Execute() या ExecuteAsyc() तरीके का इस्तेमाल करें.
• BaseClientService.Initializer इंस्टेंस पर ApiKey प्रॉपर्टी का इस्तेमाल करके, एपीआई पासकोड सेट करें.

एपीआई के बारे में जानकारी ढूंढना

काम करने वाले एपीआई पेज पर, उन सभी एपीआई की सूची दिखती है जिन्हें इस लाइब्रेरी का इस्तेमाल करके ऐक्सेस किया जा सकता है. साथ ही, दस्तावेज़ों के लिंक भी दिए गए हैं.

एपीआई ब्राउज़ करने, उपलब्ध तरीकों की सूची बनाने, और अपने ब्राउज़र से एपीआई कॉल आज़माने के लिए, एपीआई एक्सप्लोरर का भी इस्तेमाल किया जा सकता है.