शुरू करें

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

सेटअप

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

उदाहरण

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

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

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

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

अपना Simple API बटन पाएं. अपनी ऐप्लिकेशन की एपीआई कुंजी ढूंढने के लिए, नीचे दिया गया तरीका अपनाएं:

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

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

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

   • एपीआई कुंजियां: ऐसे अनुरोध में जो एपीआई 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 प्रॉपर्टी का इस्तेमाल करके, एपीआई कुंजी सेट करें.

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

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

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