समय के हिसाब से ऐक्सेस करने की सुविधा का इस्तेमाल करना

इस शुरुआती लेख में, आपको अपने खाते के लिए OAuth टोकन मिलता है. साथ ही, Data Portability API एंडपॉइंट पर बार-बार अनुरोध भेजे जाते हैं.

इस शुरुआती लेख में, उपयोगकर्ता के डेटा को समय के हिसाब से ऐक्सेस करने के लिए, Data Portability API का इस्तेमाल करने का तरीका बताया गया है. उपयोगकर्ता के डेटा को एक बार ऐक्सेस करने के लिए, Data Portability API का इस्तेमाल शुरू करना लेख पढ़ें. अपने अनुरोध पर समय के हिसाब से फ़िल्टर लागू करने का तरीका जानने के लिए, समय के हिसाब से फ़िल्टर लागू करना लेख पढ़ें.

आपको ये सब सीखने को मिलेगा

इस क्विकस्टार्ट गाइड में, आपको ये काम करने का तरीका पता चलेगा:

• मान्य OAuth टोकन देकर, InitiatePortabilityArchive एंडपॉइंट पर पुष्टि किया गया अनुरोध भेजें. जवाब में मान्य job_id होना चाहिए.
• GetPortabilityArchiveState एंडपॉइंट पर पुष्टि किया गया अनुरोध भेजें. जवाब में, जॉब की मान्य स्थिति और जॉब पूरा होने पर, हस्ताक्षर किया गया यूआरएल होना चाहिए.
• पुष्टि किए गए अनुरोध को, मान्य OAuth टोकन के साथ InitiatePortabilityArchive एंडपॉइंट पर, फिर से भेजें. इसके लिए, वही क्रेडेंशियल इस्तेमाल करें. अगर अनुरोध, पहले अनुरोध के 24 घंटे के अंदर किया जाता है, तो यह FAILED_PRECONDITION कोड वाली गड़बड़ी दिखाता है.

ज़रूरी शर्तें

यह क्विकस्टार्ट चलाने के लिए, आपको ये काम करने होंगे:

• पुष्टि करें कि Data Portability API, आपके देश/इलाके में उपयोगकर्ताओं के लिए उपलब्ध है. इस सुविधा के साथ काम करने वाले देशों और इलाकों की सूची के लिए, "किसी तीसरे पक्ष के साथ अपने डेटा की कॉपी शेयर करना" पेज पर, आम तौर पर पूछे जाने वाले सवाल देखें.
• Data Portability API के लिए, सेटअप करने का तरीका पूरा करें.
• सर्वर-साइड वेब ऐप्लिकेशन के लिए OAuth को कॉन्फ़िगर करने के लिए, यह तरीका अपनाएं.
  • ऑथराइज़ेशन क्रेडेंशियल बनाते समय, अपने OAuth 2.0 क्लाइंट आईडी, क्लाइंट सीक्रेट, और अनुमति वाले रीडायरेक्ट यूआरआई (उदाहरण के लिए, https://google.com) को नोट कर लें. आपको इनकी ज़रूरत, तुरंत शुरू करने के तरीके में बाद में पड़ेगी.
  • Data Portability API के लिए स्कोप कॉन्फ़िगर करते समय, ध्यान रखें कि यह क्विकस्टार्ट, myactivity.search संसाधन ग्रुप का इस्तेमाल करता है: https://www.googleapis.com/auth/dataportability.myactivity.search.
  • ऐक्सेस की अवधि चुनते समय, समय के हिसाब से ऐक्सेस की सुविधा को टेस्ट करने के लिए, आपको 30 दिन चुनना चाहिए.
• OAuth टोकन पाएं.
• आपके संगठन के मालिकाना हक वाले या उसके कंट्रोल वाले खाते का ऐक्सेस पाना. इस खाते की खोज गतिविधि का डेटा, इस शुरुआती निर्देश में एक्सपोर्ट किया जाता है.

OAuth टोकन पाना

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

OAuth टोकन पाने के लिए:

1. ऐसा यूआरएल बनाएं जो कुछ ऐसा दिखे.

   https://accounts.google.com/o/oauth2/v2/auth?
   client_id=client_id&
   redirect_uri=redirect_uri&
   response_type=code&
   access_type=offline&
   scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
   state=developer-specified-value

   यूआरएल में:

   • client_id आपका OAuth क्लाइंट आईडी है.
   • redirect_uri, आपका अनुमति वाला रीडायरेक्ट यूआरआई है. उदाहरण के लिए, https://google.com.

   ध्यान दें कि इस क्विकस्टार्ट के यूआरएल में, खोज गतिविधि का स्कोप इस्तेमाल किया गया है. इसके अलावा, YouTube पर की गई गतिविधि के स्कोप या दोनों स्कोप का इस्तेमाल किया जा सकता है.

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

2. यूआरएल को अपने ब्राउज़र के पता बार में चिपकाएं और OAuth फ़्लो में दिए गए निर्देशों का पालन करें. इस फ़्लो के लिए, आपको उस खाते में साइन इन करना होगा जिसका मालिकाना हक या कंट्रोल आपके संगठन के पास है और जिसका इस्तेमाल इस शुरुआती निर्देश के लिए किया जा रहा है.

   यह वह खाता है जो OAuth स्कोप के लिए सहमति दे रहा है. सहमति वाली स्क्रीन इस तरह दिखनी चाहिए (आपकी स्क्रीन पर मौजूद टेक्स्ट, इस इमेज में मौजूद टेक्स्ट से अलग हो सकता है):

   

3. खाते के डेटा का ऐक्सेस देने के लिए स्कोप चुनें. साथ ही, यह भी चुनें कि डेटा का ऐक्सेस कितने समय के लिए शेयर करना है. जैसे, एक बार, 30 दिन या 180 दिन. इस क्विकस्टार्ट के लिए, 30 दिन चुनें.

4. सहमति देने और ऐक्सेस की अवधि तय करने के बाद, आपको रीडायरेक्ट यूआरआई—https://google.com पर भेज दिया जाएगा. पता बार में जनरेट किए गए यूआरएल में एक अनुमति कोड शामिल होता है. अगले चरण में, आपको इस कोड को OAuth टोकन के लिए बदलना होगा.

   उदाहरण के लिए, अगर उपयोगकर्ता खाता dataportability.myactivity.search स्कोप को OAuth ऐक्सेस देता है, तो जनरेट किया गया यूआरएल ऐसा दिखता है:

   https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

5. ऑथराइज़ेशन कोड को ऐक्सेस टोकन से बदलने के लिए, oauth टोकन एंडपॉइंट को इनके साथ कॉल करें:

   curl https://oauth2.googleapis.com/token\
   -H 'Content-Type: application/x-www-form-urlencoded' -X POST\
   -d 'code=your_auth_code&\
   redirect_uri=redirect_uri\
   client_id=client_id&\
   client_secret=client_secret&\
   grant_type=authorization_code'

   जवाब कुछ ऐसा दिखेगा:

   {
     "access_token": your_OAuth_token,
     "expires_in": 3920,
     "token_type": "Bearer",
     "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
     "refresh_token": your_refresh_token,
     "refresh_token_expires_in": 2591999
   }

   यूआरएल में, your_OAuth_token एक स्ट्रिंग है, जो टोकन को दिखाती है.

   refresh_token_expires_in फ़ील्ड में सेकंड में जानकारी दिखती है. इससे पता चलता है कि उपयोगकर्ता ने ऐक्सेस के लिए 30 दिन (2,592,000 सेकंड) या 180 दिन (1,55,52,000 सेकंड) में से क्या चुना है. अगर आपके ऐप्लिकेशन का पब्लिश करने का स्टेटस टेस्टिंग है, तो उपयोगकर्ता के चुने गए विकल्प के बावजूद, आपके पास सात दिन (604800 सेकंड) का ऐक्सेस होगा.

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

6. OAuth टोकन की पुष्टि करने के लिए, इस यूआरएल को अपने ब्राउज़र में चिपकाएं:

   https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token

   रिस्पॉन्स कुछ ऐसा दिखेगा:

   {
     "azp": <your_azp_value>,
     "aud": <your_aud_value>,
     "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
     "exp": "1694210968",
     "expires_in": "3334",
     "access_type": "online"
   }
   

   अनुरोध करने के लिए, आपको azp या aud फ़ील्ड की ज़रूरत नहीं है. azpफ़ील्ड, प्रज़ेंटर के client_id को दिखाता है. साथ ही, aud फ़ील्ड से उस ऑडियंस की पहचान की जाती है जिसके लिए यह टोकन बनाया गया है. यह ऑडियंस, आपके ऐप्लिकेशन के किसी क्लाइंट आईडी के बराबर होगी.

   ध्यान दें: एचटीटीपी GET अनुरोध भेजकर भी टोकन की पुष्टि की जा सकती है.

7. अपना OAuth टोकन और एपीआई पासकोड इकट्ठा करें. Data Portability API को कॉल करने के लिए, आपको इनकी ज़रूरत होगी.

एंडपॉइंट पर अनुरोध भेजना

इस क्विकस्टार्ट में, Data Portability API के एंडपॉइंट को कॉल करने के लिए, curl कमांड का इस्तेमाल किया जाता है. इन निर्देशों के लिए, आपको पहले से इकट्ठा किया गया OAuth टोकन और एपीआई पासकोड डालना होगा.

Data Portability API को कॉल करने के लिए:

1. सबसे पहले, InitiatePortabilityArchive एंडपॉइंट पर पुष्टि किया गया अनुरोध भेजा जाता है. इस अनुरोध से, संग्रह करने की प्रोसेस शुरू हो जाती है.

   यहां दिया गया curl कमांड चलाएं:

   curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{"resources":["myactivity.search"]}' \
   https://dataportability.googleapis.com/v1/portabilityArchive:initiate

   कमांड में:

   • your_OAuth_token आपका OAuth टोकन है.
   चेतावनी: resources पैरामीटर में सिर्फ़ वे OAuth स्कोप शामिल होने चाहिए जिन्हें ऐक्सेस दिया गया था. इस उदाहरण में, सिर्फ़ myactivity.search को अनुमति दी गई थी. अगर आपने अन्य संसाधन ग्रुप शामिल किए हैं, तो आपको गड़बड़ी का मैसेज दिखेगा. ज़्यादा जानकारी के लिए, दायरे से जुड़ी पाबंदियां देखें.

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

   {
     "archiveJobId": "<your_job_id>"
     "accessType": "ACCESS_TYPE_TIME_BASED"
   }
   

   मान्य OAuth टोकन न देने पर, गड़बड़ी का यह मैसेज दिखता है:

   Request had invalid authentication credentials. Expected OAuth 2.0 access
   token, login cookie or other valid authentication credential. See
   https://developers.google.com/identity/sign-in/web/devconsole-project.

2. इसके बाद, संग्रहित करने के प्रोसेस की स्थिति देखने के लिए, GetPortabilityArchiveState एंडपॉइंट पर पुष्टि किया गया अनुरोध भेजा जाता है.

   यहां दिया गया curl कमांड चलाएं:

   curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
   -H "Content-Type: application/json; charset=utf-8" \
   https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState

   कमांड में:

   • your_OAuth_token आपका OAuth टोकन है.
   • your_job_id, InitiatePortabilityArchive के अनुरोध से मिला जॉब आईडी है.

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

   {
     "state": "IN_PROGRESS"
   }
   

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

   {
     "state": "COMPLETE",
     "urls": [
       "<signed_url>"
     ]
   }
   

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

   ध्यान दें: संग्रह करने की प्रोसेस पूरी होने में लगने वाला समय, संग्रह के साइज़ पर निर्भर करता है. ज़्यादा से ज़्यादा सात दिन के लिए.

   अगर आपको जवाब में FAILED स्टेटस मिलता है, तो RetryPortabilityArchive तरीके का इस्तेमाल करके, एक्सपोर्ट करने की कोशिश फिर से की जा सकती है.

3. InitiatePortabilityArchive एंडपॉइंट पर पुष्टि वाला अनुरोध भेजने के लिए, पिछले निर्देश को दोहराएं.

   curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
   -H "Content-Type: application/json; charset=utf-8" \
   --data '{"resources":["myactivity.search"]}' \
   https://dataportability.googleapis.com/v1/portabilityArchive:initiate

   कमांड में:

   • your_OAuth_token आपका OAuth टोकन है.

   जवाब में यह जानकारी दिखनी चाहिए कि आपने myactivity.search संसाधन को पहले ही एक्सपोर्ट कर लिया है. साथ ही, इसमें यह भी बताया जाना चाहिए कि दोबारा कोशिश करने के लिए, आपको कब तक इंतज़ार करना होगा.

   ...
     "error": {
       "code": 429,
       "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
       "status": "RESOURCE_EXHAUSTED",
       "details": [
         {
           "@type": "type.googleapis.com/google.rpc.ErrorInfo",
           "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
           "domain": "dataportability.googleapis.com"
     "metadata": {
       "previous_job_ids": "#{previous_job_ids}"
       "access_type": "ACCESS_TYPE_TIME_BASED"
       "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
   ...
   

4. 24 घंटे बाद, नए एक्सपोर्ट का अनुरोध किया जा सकता है. हालांकि, इसके लिए आपको पहले अपने रीफ़्रेश टोकन को नए ऐक्सेस टोकन से बदलना होगा.

   curl https://oauth2.googleapis.com/token\
   -H 'Content-Type: application/x-www-form-urlencoded' -X POST\
   -d 'refresh_token=your_refresh_token&\
   client_id=client_id&\
   client_secret=client_secret&\
   grant_type=refresh_token'

   जवाब कुछ ऐसा दिखेगा:

   {
     "access_token": your_OAuth_token,
     "expires_in": 3920,
     "token_type": "Bearer",
     "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
     "refresh_token_expires_in": 2505599
   }

   अगर उपयोगकर्ता ऐक्सेस को रिन्यू करता है, तो ऐक्सेस खत्म होने का नया समय refresh_token_expires_in फ़ील्ड में दिखता है.

   InitiatePortabilityArchive और GetPortabilityArchiveState के चरणों को दोहराने के लिए, नए ऐक्सेस टोकन का इस्तेमाल किया जा सकता है.