आरंभ करें

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

सेटअप

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

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

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

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

1. आसान एपीआई ऐक्सेस (एपीआई पासकोड)

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

एपीआई पासकोड: अपने ऐप्लिकेशन की पुष्टि करने के लिए, एपीआई पासकोड एपीआई कंसोल प्रोजेक्ट के लिए. आपके ऐप्लिकेशन के ज़रिए किए जाने वाले हर आसान ऐक्सेस कॉल में यह कुंजी शामिल होनी चाहिए.

2. आधिकारिक एपीआई ऐक्सेस (OAuth 2.0)

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

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

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

Client-ID और क्लाइंट सीक्रेट: ये स्ट्रिंग आपके ऐप्लिकेशन की खास तौर पर पहचान करती हैं और इनका इस्तेमाल टोकन पाने के लिए किया जाता है. इन्हें API Console पर आपके प्रोजेक्ट के लिए बनाया जाता है. Client-ID तीन तरह के होते हैं. इसलिए, यह पक्का करें कि आपके आवेदन का टाइप सही हो:

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

उदाहरण

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

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

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

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

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

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

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

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

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

     एपीआई, एपीआई पासकोड पर कई तरह की पाबंदियों के साथ काम करता है. अगर एपीआई पासकोड को ज़रूरत पहले से मौजूद नहीं है, तो इसके हिसाब से कंसोल में 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);
                }
            }
        }
    }
}

एपीआई पासकोड इस्तेमाल करने से जुड़ी सलाह:

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

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

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

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