Data Portability API का इस्तेमाल शुरू करना

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

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

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

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

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

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

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

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

OAuth टोकन पाना

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

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

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

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

   https://accounts.google.com/o/oauth2/v2/auth?
   client_id=client_id&
   redirect_uri=redirect_uri&
   response_type=token&
   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 दिन. इस शुरुआती सेटअप के लिए, सिर्फ़ एक बार को चुनें.

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

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

   https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

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

   अहम जानकारी: आपके OAuth ऐक्सेस टोकन की समयसीमा एक घंटे में खत्म हो जाएगी. अगर आपको नया टोकन जनरेट करना है, तो पिछले चरणों का पालन करें.

5. 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 अनुरोध भेजकर भी टोकन की पुष्टि की जा सकती है.

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

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

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

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

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

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

   {
     'archiveJobId': '<your_job_id>'
     'accessType': 'ACCESS_TYPE_ONE_TIME'
   }
   

   मान्य 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 -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. Please call ResetAuthorization and re-obtain consent before trying again.",
       "status": "RESOURCE_EXHAUSTED",
       "details": [
         {
           "@type": "type.googleapis.com/google.rpc.ErrorInfo",
           "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
           "domain": "dataportability.googleapis.com"
     "metadata": {
       "previous_job_ids": "{previous_job_ids}"
       "access_type": "ACCESS_TYPE_ONE_TIME"
   ...
   

4. ResetAuthorization एंडपॉइंट पर पुष्टि किया गया अनुरोध भेजें. इस अनुरोध से, उपयोगकर्ता से मिले सभी OAuth स्कोप रद्द हो जाते हैं. साथ ही, आपको उस संसाधन ग्रुप के लिए InitiatePortabilityArchive को कॉल करने की अनुमति मिलती है जिसका आपने पहले इस्तेमाल किया है.

   curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
   -H "Content-Type: application/json; charset=utf-8" \
   https://dataportability.googleapis.com/v1/authorization:reset

   कमांड में:

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

   इस निर्देश से कोई जवाब नहीं मिलता.

5. (ज़रूरी नहीं) अनुमति को रीसेट करने के बाद, 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 टोकन है.

   आपको जवाब में गड़बड़ी का मैसेज दिखेगा, क्योंकि आपने जो OAuth टोकन दिया है उसे रद्द कर दिया गया है.

   ...
     "error": {     
       "code": 401,    
           "message": "Request had invalid authentication credentials. Expected
           OAuth 2 access token, login cookie or other valid authentication
           credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
           "status": "UNAUTHENTICATED"
     }