इस पेज का अनुवाद Cloud Translation API से किया गया है.

API (एपीआई) का इस्तेमाल करना

परिचय

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

एपीआई को भेजे गए सभी कॉल की पुष्टि नहीं की गई है. इनमें JSON-आधारित REST वाले अनुरोध शामिल हैं, जो यूआरएल का इस्तेमाल करते हैं, जैसे कि यूआरएल, https से शुरू होते हैं.

अगर आप Google API डिस्कवरी सर्विस के सिद्धांतों के बारे में नहीं जानते, तो आपको कोड शुरू करने से पहले शुरू करना पढ़ना चाहिए.

खोज से जुड़े दस्तावेज़ का फ़ॉर्मैट

इस सेक्शन में, डिस्कवरी दस्तावेज़ की खास जानकारी होती है.

नीचे दिए गए सभी उदाहरण, Google Cloud सेवा प्रबंधन एपीआई के डिस्कवरी दस्तावेज़ का इस्तेमाल करते हैं. आप GET का अनुरोध करके, Google Cloud सेवा प्रबंधन एपीआई के लिए डिस्कवरी दस्तावेज़ लोड कर सकते हैं:

GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1

डिस्कवरी दस्तावेज़ के फ़ॉर्मैट में ऐसी जानकारी होती है जो छह मुख्य कैटगरी में आती है:

एपीआई की बुनियादी जानकारी.
एपीआई के लिए पुष्टि करने से जुड़ी जानकारी.
एपीआई के डेटा की जानकारी देने वाला संसाधन और स्कीमा की जानकारी.
एपीआई और #तरीके के बारे में जानकारी.
एपीआई के साथ काम करने वाली किसी भी कस्टम सुविधा के बारे में जानकारी.
एपीआई के खास एलिमेंट के बारे में बताने वाला इनलाइन दस्तावेज़.

इनमें से हर डिस्कवरी दस्तावेज़ सेक्शन के बारे में नीचे बताया गया है. हर प्रॉपर्टी के बारे में ज़्यादा जानकारी के लिए, पहचान फ़ाइल दस्तावेज़ देखें.

एपीआई के बारे में बुनियादी जानकारी

डिस्कवरी दस्तावेज़ में एपीआई की खास प्रॉपर्टी का सेट होता है:

"kind": "discovery#restDescription",
"name": "servicemanagement",
"version": "v1",
"title": "Service Management API",
"description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.",
"protocol": "rest",
"rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live",
"servicePath": "",

एपीआई-लेवल की इन प्रॉपर्टी में, एपीआई के किसी खास वर्शन का ब्यौरा होता है. इनमें name, version, title, और description शामिल हैं. protocol का हमेशा rest का तय मान होता है, क्योंकि एपीआई डिस्कवरी सेवा सिर्फ़ एपीआई को ऐक्सेस करने के RESTful तरीकों के साथ काम करती है.

servicePath फ़ील्ड से इस खास एपीआई वर्शन के लिए पाथ प्रीफ़िक्स दिखता है.

पुष्टि करना

auth सेक्शन में, एपीआई के OAuth 2.0 पुष्टि के तरीकों की जानकारी है. OAuth 2.0 के दायरे का इस्तेमाल करने के तरीके के बारे में ज़्यादा जानने के लिए, Google API ऐक्सेस करने के लिए OAuth 2.0 का इस्तेमाल करना लेख पर जाएं.

auth सेक्शन में, नेस्ट किया हुआ oauth2 और scopes सेक्शन शामिल है. scopes सेक्शन, स्कोप वैल्यू से स्कोप के बारे में ज़्यादा जानकारी के लिए एक की/वैल्यू मैपिंग है:

"auth": {
  "oauth2": {
    "scopes": {
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management.readonly": {
        "description": "View your Google API service configuration"
      },
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "View and manage your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

auth सेक्शन सिर्फ़ किसी खास एपीआई के दायरे बताता है. यह जानने के लिए कि ये दायरे किसी एपीआई से कैसे जुड़े हैं, नीचे दिए गए तरीके सेक्शन को देखें.

संसाधन और स्कीमा

एपीआई और #39;s की कार्रवाइयां, resources नाम के डेटा ऑब्जेक्ट पर काम करती हैं. डिस्कवरी दस्तावेज़, संसाधनों के कॉन्सेप्ट पर आधारित है. डिस्कवरी के हर दस्तावेज़ में टॉप लेवल का resources सेक्शन होता है. इसमें, एपीआई से जुड़े सभी संसाधन शामिल होते हैं. उदाहरण के लिए, Google Cloud सेवा प्रबंधन एपीआई में services संसाधन और operations लेवल की टॉप लेवल resources में मौजूद, services संसाधन में तीन सब रिसॉर्स, configs, rollouts, और consumers शामिल हैं:

"resources": {
  "services": {
    // Methods and sub-resources associated with the services resource
    "configs": {
      // Methods and sub-resources associated with the services.configs resource
    },
    "rollouts": {
      // Methods and sub-resources associated with the services.rollouts resource
    },
    "consumers": {
      // Methods and sub-resources associated with the services.consumers resource
    }
  },
  "operations": {
    // Methods and sub-resources associated with the operations resource
  }
}

हर संसाधन सेक्शन में उस संसाधन से जुड़े तरीके होते हैं. उदाहरण के लिए, Google Cloud Service Management API में services.rollouts रिसॉर्स से जुड़े तीन तरीके हैं: get, list, और create.

स्कीमा से आपको यह पता चलता है कि एपीआई में मौजूद संसाधन कैसे दिखते हैं. डिस्कवरी के हर दस्तावेज़ में schemas लेवल का टॉप लेवल होता है, जिसमें ऑब्जेक्ट के लिए स्कीमा आईडी का नाम/वैल्यू का जोड़ा होता है. स्कीमा आईडी हर एपीआई के लिए अलग-अलग होते हैं और इनका इस्तेमाल डिस्कवरी दस्तावेज़ के methods सेक्शन में खास तौर पर स्कीमा की पहचान करने के लिए किया जाता है:

"schemas": {
  "Rollout": {
    // JSON Schema of the Rollout resource.
  }
}

एपीआई डिस्कवरी सर्विस, स्कीमा दिखाने के लिए JSON स्कीमा ड्राफ़्ट-03 का इस्तेमाल करती है. यहां यूआरएल संसाधन के लिए JSON स्कीमा का स्निपेट दिया गया है, जिसमें जवाब देने के लिए एक असल संसाधन भी है:

रोल आउट रिसॉर्स JSON स्कीमा:

रोल आउट संसाधन का असल जवाब:

{
  "Rollout": {
    "id": "Rollout",
    "type": "object",
    "description": "...",
    "properties": {
      "serviceName": {
        "type": "string",
        "description": "..."
      },
      "rolloutId": {
        "type": "string",
        "description": "..."
      },
      "status": {
        "type": "string",
        "enum": [
          "ROLLOUT_STATUS_UNSPECIFIED",
          "IN_PROGRESS",
          "SUCCESS",
          "CANCELLED",
          "FAILED",
          "PENDING",
          "FAILED_ROLLED_BACK"
        ],
        "enumDescriptions": [
          ...
        ],
        "description": "..."
      },
      "trafficPercentStrategy": {
        "$ref": "TrafficPercentStrategy",
        "description": "..."
      },
      "deleteServiceStrategy": { ... },
      "createTime": { ... },
      "createdBy": { ... }
    }
  }
}

{
  "serviceName": "discovery.googleapis.com",
  "rolloutId": "2020-01-01R0",
  "status": "SUCCESS",
  "trafficPercentStrategy":{
    "precentages":{
      "2019-12-01R0": 70.00,
      "2019-11-01R0": 30.00
    }
  }
}

बोल्ड में दिए गए फ़ील्ड, JSON स्कीमा और असल जवाब के बीच मैपिंग दिखाते हैं.

स्कीमा में दूसरे स्कीमा के रेफ़रंस भी हो सकते हैं. अगर कोई क्लाइंट लाइब्रेरी बनाई जा रही है, तो आपको अपने डेटा मॉडल की क्लास में, एपीआई के ऑब्जेक्ट को असरदार तरीके से मॉडल करने में मदद मिल सकती है. ऊपर दिए गए Rollout उदाहरण में, trafficPercentStrategy प्रॉपर्टी असल में आईडी TrafficPercentStrategy वाले स्कीमा का रेफ़रंस है. schemas सेक्शन को देखने पर, आपको TrafficPercentStrategy स्कीमा दिखेगा. इस स्कीमा की वैल्यू को trafficPercentStrategy प्रॉपर्टी में Rollout रिसॉर्स से बदला जा सकता है (ध्यान दें कि $ref सिंटैक्स, JSON स्कीमा स्पेसिफ़िकेशन से आता है).

मेथड, अनुरोधों और रिस्पॉन्स बॉडी को दिखाते समय भी स्कीमा का रेफ़रंस दे सकते हैं. ज़्यादा जानकारी के लिए तरीके सेक्शन देखें.

तरीके

खोज से जुड़े दस्तावेज़ का मुख्य हिस्सा अलग-अलग तरीकों से बनाया गया है. मेथड, वे कार्रवाइयां हैं जिन्हें एपीआई पर किया जा सकता है. आपको methods दस्तावेज़, डिस्कवरी दस्तावेज़ के अलग-अलग हिस्सों में दिखेगा. इसमें टॉप लेवल (जिसे एपीआई लेवल के तरीके भी कहा जाता है) या resources लेवल पर शामिल है.

"methods": {
  // API-level methods
}
"resources": {
  "resource1": {
    "methods": {
      // resource-level methods
    }
    "resources": {
      "nestedResource": {
        "methods": {
          // methods can even be found in nested-resources
        }
      }
    }
  }
}

किसी एपीआई में एपीआई लेवल के तरीके हो सकते हैं. हालांकि, किसी रिसॉर्स में methods सेक्शन होना ज़रूरी है.

हर methods सेक्शन में, तरीके के नाम से लेकर उस तरीके के बारे में ज़्यादा जानकारी देने वाला एक की/वैल्यू मैप होता है. नीचे दिए गए उदाहरण में तीन तरीके, get, list, और create के बारे में बताया गया है:

"methods": {
  "get": { //details about the "get" method },
  "list": { //details about the "list" method },
  "create": { //details about the "create" method }
}

आखिर में, हर तरीके के सेक्शन में उस प्रॉपर्टी के बारे में अलग-अलग प्रॉपर्टी की जानकारी होती है. यहां get तरीके का एक उदाहरण दिया गया है:

"get": {
  "id": "servicemanagement.services.rollouts.get",
  "path": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "httpMethod": "GET",
  "description": "Gets a service configuration rollout.",
  "response": { "$ref": "Rollout" },
  "parameters": { // parameters related to the method },
  "parameterOrder": [ // parameter order related to the method ],
  "scopes": [ // OAuth 2.0 scopes applicable to this method ],
  "mediaUpload": { // optional media upload information },
},

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

बंदूक पर लगने वाली दूरबीन

इस दस्तावेज़ में पहले से तय auth सेक्शन में, किसी खास एपीआई के साथ काम करने वाले सभी दायरों के बारे में जानकारी है. अगर कोई तरीका इनमें से किसी एक दायरे के साथ काम करता है, तो उसके दायरे की कैटगरी होगी. इस तरीके में काम करने वाले हर दायरे के लिए एक एंट्री होती है. उदाहरण के लिए, Google Cloud Service Management API get तरीके का scopes सेक्शन कुछ ऐसा दिखता है:

"scopes": [
  "https://www.googleapis.com/auth/cloud-platform",
  "https://www.googleapis.com/auth/cloud-platform.read-only",
  "https://www.googleapis.com/auth/service.management",
  "https://www.googleapis.com/auth/service.management.readonly"
]

ध्यान दें कि आपके ऐप्लिकेशन में इस्तेमाल करने के लिए पुष्टि करने का दायरा अलग-अलग होता है. यह इस बात पर निर्भर करता है कि कॉल करने के कौनसे तरीके इस्तेमाल किए जा रहे हैं और तरीके के साथ कौनसे पैरामीटर भेजे जाते हैं. इसलिए, डेवलपर के पास यह चुनने का अधिकार होता है कि उसे किस क्षेत्र का इस्तेमाल करना है. डिस्कवरी सिर्फ़ उन दस्तावेज़ों को दिखाती है जो किसी तरीके के लिए मान्य हैं.

अनुरोध करें और जवाब दें

अगर तरीके में अनुरोध या जवाब का मुख्य हिस्सा है, तो इन्हें क्रम के request या response सेक्शन में दर्ज किया जाता है. ऊपर दिए गए get उदाहरण में, तरीके का मुख्य हिस्सा response है:

"response": {
  "$ref": "Rollout"
}

ऊपर दिया गया सिंटैक्स बताता है कि जवाब का मुख्य हिस्सा, Rollout की आईडी वाले JSON स्कीमा से तय होता है. इस स्कीमा को टॉप-लेवल स्कीमा सेक्शन में देखा जा सकता है. अनुरोध का जवाब देने और जवाब देने वाले दोनों सिस्टम, स्कीमा का रेफ़रंस देने के लिए, $ref सिंटैक्स का इस्तेमाल करते हैं.

पैरामीटर

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

"parameters": {
  "serviceName": {
    "type": "string",
    "description": "Required. The name of the service.",
    "required": true,
    "location": "path"
  },
  "rolloutId": { ... }
},
"parameterOrder": [
  "serviceName",
  "rolloutId"
]

ऊपर दिए गए उदाहरण में, get मेथड के लिए दो पैरामीटर हैं:serviceName और rolloutId. पैरामीटर path या यूआरएल query में जा सकते हैं; location प्रॉपर्टी बताती है कि क्लाइंट लाइब्रेरी को पैरामीटर कहां रखना चाहिए.

कई दूसरी प्रॉपर्टी भी पैरामीटर के बारे में बताती हैं. इनमें पैरामीटर डेटा type, खास तौर पर टाइप की गई भाषाओं के लिए इस्तेमाल होता है. साथ ही, इसमें पैरामीटर required भी शामिल होता है और पैरामीटर enum है या नहीं. प्रॉपर्टी के बारे में ज़्यादा जानकारी के लिए, पहचान गाइड देखें.

पैरामीटर का ऑर्डर

क्लाइंट लाइब्रेरी के इंटरफ़ेस इंटरफ़ेस तैयार करने के कई तरीके हैं. इसका एक तरीका यह है कि मैथ सिग्नेचर में, हर एपीआई पैरामीटर के साथ एक तरीका सेट करें. हालांकि, JSON के फ़ॉर्मैट में बदलाव नहीं किया जा सकता. इसलिए, तरीके से यह नहीं पता चल सकता कि पैरामीटर को मेथड सिग्नेचर में कैसे पैरामीटर करना है. parameterOrder अरे, अनुरोध करने के लिए पैरामीटर के क्रम को तय करता है. श्रेणी में, क्रम के हिसाब से हर पैरामीटर का नाम दिया जाता है. इसमें पाथ या क्वेरी पैरामीटर शामिल हो सकते हैं. हालांकि, श्रेणी में मौजूद हर पैरामीटर ज़रूरी है. ऊपर दिए गए उदाहरण में, Java में हस्ताक्षर करने का तरीका कुछ इस तरह दिख सकता है:

public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);

parameterOrder कलेक्शन की पहली वैल्यू, serviceName, मेथड सिग्नेचर में पहला एलिमेंट भी है. अगर parameterOrder कैटगरी में अन्य पैरामीटर थे, तो वे serviceName पैरामीटर के बाद जाएंगे. parameterOrder कैटगरी में सिर्फ़ ज़रूरी पैरामीटर होते हैं. इसलिए, उपयोगकर्ताओं के लिए वैकल्पिक पैरामीटर भी तय करना एक अच्छा तरीका है. ऊपर दिए गए उदाहरण में, ऐसा optionalParameters मैप के साथ किया गया है.

मीडिया अपलोड करें

अगर किसी तरीके से मीडिया अपलोड करने की सुविधा मिलती है, जैसे कि इमेज, ऑडियो या वीडियो, तो mediaUpload सेक्शन में उस मीडिया को अपलोड करने की सुविधा देने वाले प्रोटोकॉल और जगह की जानकारी के दस्तावेज़ तैयार किए जाते हैं. इस सेक्शन में बताया गया है कि किस तरह के अपलोड प्रोटोकॉल काम करते हैं. साथ ही, यह भी बताया गया है कि किस तरह के मीडिया अपलोड किए जा सकते हैं:

"supportsMediaUpload": true,
"mediaUpload": {
  "accept": [
    "image/*"
  ],
  "maxSize": "10MB",
  "protocols": {
    "simple": {
      "multipart": true,
      "path": "/upload/storage/v1beta1/b/{bucket}/o"
    },
    "resumable": {
     "multipart": true,
     "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
    }
  }
}

ऊपर दिए गए उदाहरण में, supportsMediaUpload प्रॉपर्टी की वैल्यू एक बूलियन वैल्यू है. इससे यह तय होता है कि इस तरीके से मीडिया अपलोड किया जा सकता है या नहीं. अगर वैल्यू सही पर सेट की गई है, तो mediaUpload सेक्शन में इस बात की जानकारी दी जाएगी कि किस तरह का मीडिया अपलोड किया जा सकता है.

accept प्रॉपर्टी, मीडिया रेंज की सूची है, जो यह तय करती है कि कौनसे माइम टाइप अपलोड किए जा सकते हैं. ऊपर दिए गए उदाहरण में दिखाया गया एंडपॉइंट, किसी भी इमेज फ़ॉर्मैट को स्वीकार करेगा.

maxSize प्रॉपर्टी में अपलोड के साइज़ की सीमा तय की गई है. यह वैल्यू, एमबी, जीबी या टीबी की यूनिट में एक स्ट्रिंग होती है. ऊपर दिए गए उदाहरण में, अपलोड करने का साइज़ 10 एमबी से ज़्यादा नहीं हो सकता. ध्यान दें कि यह मान उस उपयोगकर्ता के लिए किसी व्यक्तिगत उपयोगकर्ता के बचे हुए स्टोरेज कोटा को नहीं दिखाता है. इसलिए, हो सकता है कि अपलोड maxSize से कम हो, लेकिन क्लाइंट लाइब्रेरी को अब भी ऐसे अपलोड को हैंडल करने के लिए तैयार किया जाना चाहिए जो कम जगह की वजह से काम न करता हो.

protocols सेक्शन में, अपलोड करने के ऐसे प्रोटोकॉल दिए गए हैं जिन पर कोई तरीका काम करता है. simple प्रोटोकॉल, किसी एक एचटीटीपी अनुरोध में, दिए गए एंडपॉइंट पर मीडिया को पोस्ट कर रहा है. resumable प्रोटोकॉल का मतलब है कि path यूआरआई में दिया गया एंडपॉइंट, फिर से शुरू किए जा सकने वाले अपलोड प्रोटोकॉल के साथ काम करता है. अगर multipart प्रॉपर्टी true है, तो एंडपॉइंट कई हिस्सों के अपलोड स्वीकार करता है. इसका मतलब है कि JSON अनुरोध और मीडिया को एक साथ म्यूटप्लिट/मिलते-जुलते हिस्से में रैप किया जा सकता है और एक साथ भेजा जा सकता है. ध्यान दें कि simple और resumable, दोनों प्रोटोकॉल पर कई हिस्सों के लिए अपलोड की सुविधा काम कर सकती है.

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

मीडिया डाउनलोड करें

अगर किसी तरीके से मीडिया, जैसे कि इमेज, ऑडियो या वीडियो को डाउनलोड किया जा सकता है, तो इसे supportsMediaDownload पैरामीटर से दिखाया जाता है:

"supportsMediaDownload": true,

मीडिया डाउनलोड करते समय, आपको अनुरोध के यूआरएल में alt क्वेरी पैरामीटर को media पर सेट करना होगा.

अगर एपीआई मेथड की useMediaDownloadService प्रॉपर्टी true है, तो रीडायरेक्ट से बचने के लिए, servicePath से पहले /download डालें. उदाहरण के लिए, अगर servicePath और path को जोड़ने के दौरान /youtube/v3/captions/{id} का इस्तेमाल होता है, तो डाउनलोड पाथ /download/youtube/v3/captions/{id} होता है. हमारा सुझाव है कि आप /download के लिए, मीडिया डाउनलोड करने वाला यूआरएल बनाएं. भले ही, useMediaDownloadService गलत हो.

ध्यान दें: मीडिया के अपलोड और अपलोड, दोनों के लिए एक ही एपीआई तरीके का इस्तेमाल किया जा सकता है. मीडिया अपलोड करने और डाउनलोड करने के लिए, यूआरएल बनाने के लॉजिक का अनुरोध अलग से किया जाता है. साथ ही, यह एक-दूसरे के काम में रुकावट नहीं डालता. इस वजह से, मीडिया अपलोड करने के लिए एपीआई के इस तरीके का एक /download/... यूआरएल और मीडिया अपलोड करने के लिए एक /upload/... यूआरएल होगा. हालांकि, एक ही अनुरोध पर कोई मीडिया अपलोड और डाउनलोड नहीं किया जा सकता.

सामान्य पैरामीटर

सबसे ऊपर के लेवल के डिस्कवरी दस्तावेज़ में parameters प्रॉपर्टी होती है. यह सेक्शन, हर तरीके के लिए पैरामीटर सेक्शन से मिलता-जुलता है. हालांकि, ये पैरामीटर, एपीआई में किसी भी तरीके पर लागू किए जा सकते हैं.

उदाहरण के लिए, Google Cloud Service Management API के पाने, शामिल करने या सूची बनाने के तरीकों के अनुरोध पैरामीटर में prettyPrint पैरामीटर हो सकता है. यह पैरामीटर उन सभी तरीकों के लिए रिस्पॉन्स को ऐसे फ़ॉर्मैट में फ़ॉर्मैट करेगा जिसे लोग पढ़ सकें. यहां आम पैरामीटर की सूची दी गई है:

पैरामीटर	लिंक	नोट	लागू होने की शर्तें
`access_token`	मौजूदा उपयोगकर्ता के लिए OAuth 2.0 टोकन.	OAuth 2.0 टोकन देने का एक तरीका.
`alt`	जवाब के लिए डेटा फ़ॉर्मैट.	मान्य मान: `json`, `atom`, `csv`. डिफ़ॉल्ट मान: हर एपीआई के हिसाब से अलग-अलग होता है. सभी एपीआई के लिए सभी वैल्यू उपलब्ध नहीं होती हैं.	सभी संसाधनों की सभी कार्रवाइयों पर लागू होता है.
`callback`	कॉलबैक फ़ंक्शन.	JavaScript के उस कॉलबैक फ़ंक्शन का नाम जो रिस्पॉन्स को हैंडल करता है. JavaScript JSON-P अनुरोधों में इस्तेमाल किया जाता है.
`fields`	सिलेक्टर, जवाब में शामिल करने के लिए फ़ील्ड का एक सबसेट तय करता है.	ज़्यादा जानकारी के लिए, आंशिक जवाब का दस्तावेज़ देखें. बेहतर परफ़ॉर्मेंस के लिए इस्तेमाल करें.
`key`	एपीआई कुंजी. (ज़रूरी है*)	*अगर आप OAuth 2.0 टोकन नहीं देते हैं, तो यह ज़रूरी है. आपकी एपीआई कुंजी आपके प्रोजेक्ट की पहचान करती है. साथ ही, आपको एपीआई का ऐक्सेस, कोटा, और रिपोर्ट भी उपलब्ध कराती है. API (एपीआई) कंसोल से अपने प्रोजेक्ट की API (एपीआई) कुंजी पाएं.
`prettyPrint`	पहचान और लाइन ब्रेक से रिस्पॉन्स मिलता है.	अगर रिस्पॉन्स `true` के तौर पर दिखता है, तो रिस्पॉन्स को ऐसे फ़ॉर्मैट में दिखाया जाता है जिसे आसानी से पढ़ा जा सके. डिफ़ॉल्ट मान: हर एपीआई के हिसाब से अलग-अलग होता है. ऐसा `false` होने पर, रिस्पॉन्स पेलोड का साइज़ कम हो सकता है. इससे, कुछ जगहों पर बेहतर परफ़ॉर्मेंस हो सकती है.
`quotaUser`	`userIp` का विकल्प.	आप उपयोगकर्ता के सर्वर पते का इस्तेमाल न करने पर भी, सर्वर-साइड ऐप्लिकेशन से हर उपयोगकर्ता के लिए कोटा लागू करने की सुविधा देते हैं. उदाहरण के लिए, ऐसा उन ऐप्लिकेशन के लिए हो सकता है जो उपयोगकर्ता की ओर से App Engine पर क्रॉन जॉब चलाते हैं. आप ऐसी आर्बिट्ररी स्ट्रिंग चुन सकते हैं जिससे किसी उपयोगकर्ता की खास पहचान होती हो. हालांकि, इसमें 40 वर्ण से ज़्यादा नहीं हो सकते. अगर दोनों दिए गए हैं, तो `userIp` को ओवरराइड करता है. कैपिंग इस्तेमाल के बारे में ज़्यादा जानें.
`userIp`	उस असली उपयोगकर्ता का आईपी पता जिसके लिए एपीआई कॉल किया जा रहा है.	इस नीति की मदद से, सर्वर साइड ऐप्लिकेशन से एपीआई को कॉल करते समय, हर उपयोगकर्ता के लिए कोटा लागू किया जा सकता है. कैपिंग इस्तेमाल के बारे में ज़्यादा जानें.

सुविधाएं

कुछ ऐसे मामले हैं जिनमें एपीआई, बाकी डिस्कवरी दस्तावेज़ के दायरे से बाहर, कस्टम सुविधाओं की सुविधा देते हैं. इन्हें features कैटगरी में इकट्ठा किया जाता है. सुविधाओं की कैटगरी में, एपीआई से जुड़ी हर खास सुविधा के लिए एक स्ट्रिंग लेबल होता है. फ़िलहाल, dataWrapper सुविधा का इस्तेमाल किया जा सकता है. हालांकि, आने वाले समय में दूसरी सुविधाएं भी इस्तेमाल की जा सकती हैं.

"features": dataWrapper

dataWrapper सुविधा यह बताती है कि एपीआई से मिले सभी अनुरोध और जवाब, data JSON ऑब्जेक्ट में रैप किए गए हैं. यह सुविधा Google API के पुराने वर्शन की सुविधा है. हालांकि, अब इसका इस्तेमाल नहीं किया जा रहा है. नीचे दिए गए एपीआई dataWrapper सुविधा के साथ काम करते हैं: मॉडरेटर v1 और अनुवाद v2.

क्लाइंट लाइब्रेरी डेवलपर के तौर पर, अगर कोई एपीआई "dataWrapper" सुविधा के साथ काम करता है, तो आपको ये काम करने चाहिए:

अनुरोधों पर: अनुरोध के संसाधन को data JSON ऑब्जेक्ट में रैप करें.
जवाबों पर: data JSON ऑब्जेक्ट में संसाधन ढूंढें.

डिस्कवरी दस्तावेज़ के स्कीमा में डेटा रैपर नहीं होता है. इसलिए, आपको उन्हें साफ़ तौर पर जोड़ना और हटाना होगा. उदाहरण के लिए, मान लें कि एक एपीआई है जिसका नाम "Foo&quot है; वह ऐसा दिखता है:

{
  "id": 1,
  "foo": "bar"
}

एपीआई का इस्तेमाल करके इस संसाधन को डालने से पहले, आपको इसे किसी डेटा एलिमेंट में रैप करना होगा:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

वहीं दूसरी ओर, जब आपको एपीआई से जवाब मिलता है, तो उसमें डेटा रैपर भी होता है:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

स्कीमा से तय किए गए संसाधन को पाने के लिए, आपको डेटा रैपर हटाना होगा:

{
  "id": 1,
  "foo": "bar"
}

इनलाइन दस्तावेज़

खोज के हर दस्तावेज़ को कई description फ़ील्ड के साथ दिखाया जाता है, जो एपीआई के लिए इनलाइन दस्तावेज़ उपलब्ध कराते हैं. description फ़ील्ड को नीचे दिए गए एपीआई एलिमेंट के लिए ढूंढा जा सकता है:

एपीआई
OAuth के दायरे
संसाधन स्कीमा
एपीआई तरीके
मेथड पैरामीटर
कुछ पैरामीटर के लिए स्वीकार किए जाने वाले मान

ये फ़ील्ड खास तौर पर तब काम आते हैं, जब किसी क्लाइंट लाइब्रेरी, जैसे कि JavaDoc के लिए ऐसे दस्तावेज़ जनरेट करने होते हैं जिन्हें आसानी से पढ़ा जा सकता है.

अगले चरण

क्लाइंट लाइब्रेरी बनाना