डेटासेट बनाना

डेटासेट बनाने की प्रोसेस दो चरणों में होती है:

  1. डेटासेट बनाने का अनुरोध करें.

  2. डेटासेट में डेटा अपलोड करने का अनुरोध करें.

डेटा को पहली बार अपलोड करने के बाद, डेटासेट का नया वर्शन बनाने के लिए, उसमें नया डेटा अपलोड किया जा सकता है.

डेटासेट बनाना

डेटासेट एंडपॉइंट पर POST अनुरोध भेजकर, डेटासेट बनाएं:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

डेटासेट की जानकारी देने वाले अनुरोध में JSON बॉडी डालें. इसलिए, आपको ये करने होंगे:

  • डेटासेट के displayName के बारे में बताएं. सभी डेटासेट के लिए, displayName की वैल्यू यूनीक होनी चाहिए.

  • usage को USAGE_DATA_DRIVEN_STYLING पर सेट करें.

उदाहरण के लिए:

curl -X POST -d '{
    "displayName": "My Test Dataset", 
    "usage": "USAGE_DATA_DRIVEN_STYLING"
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets"

रिस्पॉन्स में, डेटासेट का आईडी और अन्य जानकारी, projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID के तौर पर शामिल होती है. डेटासेट को अपडेट करने या उसमें बदलाव करने का अनुरोध करते समय, डेटासेट आईडी का इस्तेमाल करें.

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "createTime": "2022-08-15T17:50:00.189682Z",
  "updateTime": "2022-08-15T17:50:00.189682Z" 
}

डेटासेट में डेटा अपलोड करना

डेटासेट बनाने के बाद, Google Cloud Storage या किसी लोकल फ़ाइल से डेटा को डेटासेट में अपलोड करें.

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

Cloud Storage से डेटा अपलोड करना

Cloud Storage से अपने डेटासेट में डेटा अपलोड करने के लिए, डेटासेट एंडपॉइंट पर POST अनुरोध भेजें. इस अनुरोध में डेटासेट का आईडी भी शामिल होता है:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

JSON अनुरोध बॉडी में:

  • Cloud Storage में मौजूद डेटा वाले संसाधन का फ़ाइल पाथ बताने के लिए, inputUri का इस्तेमाल करें. यह पाथ gs://GCS_BUCKET/FILE के तौर पर है.

    अनुरोध करने वाले उपयोगकर्ता के पास स्टोरेज ऑब्जेक्ट व्यूअर की भूमिका होनी चाहिए. इसके अलावा, उसके पास storage.objects.get अनुमति वाली कोई भी अन्य भूमिका हो सकती है. Cloud Storage का ऐक्सेस मैनेज करने के बारे में ज़्यादा जानने के लिए, ऐक्सेस कंट्रोल की खास जानकारी लेख पढ़ें.

  • डेटा के फ़ाइल फ़ॉर्मैट को बताने के लिए, fileFormat का इस्तेमाल करके इनमें से कोई एक विकल्प चुनें: FILE_FORMAT_GEOJSON (GeoJSON फ़ाइल), FILE_FORMAT_KML (KML फ़ाइल) या FILE_FORMAT_CSV (CSV फ़ाइल).

उदाहरण के लिए:

curl -X POST  -d '{
    "gcs_source":{
      "inputUri": "gs://my_bucket/my_csv_file",
      "fileFormat": "FILE_FORMAT_CSV"
    }
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import"

जवाब इस फ़ॉर्म में है:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

फ़ाइल से डेटा अपलोड करना

किसी फ़ाइल से डेटा अपलोड करने के लिए, डेटासेट एंडपॉइंट पर एक एचटीटीपी POST अनुरोध भेजें, जिसमें डेटासेट का आईडी भी शामिल हो:

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

अनुरोध में ये चीज़ें शामिल हैं:

  • Goog-Upload-Protocol हेडर को multipart पर सेट किया गया है.

  • metadata प्रॉपर्टी, किसी फ़ाइल के पाथ की जानकारी देती है. इस पाथ से यह पता चलता है कि अपलोड किए जाने वाले डेटा का टाइप क्या है: FILE_FORMAT_GEOJSON (GeoJSON फ़ाइल), FILE_FORMAT_KML (KML फ़ाइल) या FILE_FORMAT_CSV (CSV फ़ाइल).

    इस फ़ाइल का कॉन्टेंट इस फ़ॉर्मैट में होता है:

    {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
  • rawdata प्रॉपर्टी, जिसमें GeoJSON, KML या CSV फ़ाइल का पाथ बताया जाता है, जिसमें अपलोड किया जाने वाला डेटा होता है.

नीचे दिया गया अनुरोध, दो फ़ाइलों का पाथ बताने के लिए, curl -F विकल्प का इस्तेमाल करता है:

curl -X POST \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Goog-Upload-Protocol: multipart" \
  -F "metadata=@csv_metadata_file" \
  -F "rawdata=@csv_data_file" \
  "https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import"

जवाब इस फ़ॉर्म में है:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

डेटा प्रोसेसिंग की स्थिति का पता लगाना

अपलोड करने की प्रोसेस एसिंक्रोनस होती है. इसका मतलब है कि डेटासेट में डेटा अपलोड करने के लिए एपीआई कॉल के बाद, आपको डेटासेट की मदद से यह पता लगाना होगा कि डेटा डालने और प्रोसेस करने की प्रोसेस पूरी हुई या नहीं.

डेटासेट का state तय करने के लिए, डेटासेट पाएं का इस्तेमाल करें. उदाहरण के लिए, डेटा प्रोसेस होने के दौरान, state को STATE_PROCESSING पर सेट किया जाता है. जब डेटासेट आपके ऐप्लिकेशन में इस्तेमाल करने के लिए तैयार हो जाता है, तो state को STATE_COMPLETED पर सेट कर दिया जाता है.

उदाहरण के लिए, डेटासेट पर GET कॉल करें:

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46"

डेटासेट को अपलोड करने के लिए, state STATE_COMPLETED होना चाहिए:

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_COMPLETED",
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

डेटा प्रोसेसिंग न हो पाने पर, state को STATE_COMPLETED के बजाय किसी दूसरी वैल्यू पर सेट किया जाता है. जैसे, STATE_PUBLISHING_FAILED या _FAILED पर खत्म होने वाला कोई स्टेटस.

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

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_PUBLISHING_FAILED",
    "errorMessage": "INVALID_ARGUMENT: Skipping row because address could not be geocoded: 5521 18 AVENUE (from line 79)"
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

डेटा प्रोसेस करने से जुड़ी गड़बड़ियों की जानकारी पाना

डेटा इकट्ठा और प्रोसेस नहीं होने पर, errorMessage प्रॉपर्टी में गड़बड़ी के बारे में जानकारी देने वाला एक मैसेज होता है. हालांकि, गड़बड़ी का एक मैसेज, समस्याओं की पहचान करने और उन्हें ठीक करने के लिए ज़रूरी जानकारी नहीं देता.

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

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors"

रिस्पॉन्स में errors कलेक्शन शामिल है. इस कलेक्शन में, हर कॉल के लिए Status टाइप की ज़्यादा से ज़्यादा 50 गड़बड़ियां हो सकती हैं. साथ ही, इसमें कुल 500 गड़बड़ियां हो सकती हैं:

{
  "nextPageToken": "cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj",
  "errors": [
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 631)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 457)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 31)"
    },
    ...
  ]
}

अगर 50 से ज़्यादा गड़बड़ियां यानी कि एक पेज से ज़्यादा गड़बड़ियां हैं, तो nextPageToken फ़ील्ड में रिस्पॉन्स के तौर पर पेज टोकन मौजूद होता है. गड़बड़ियों का अगला पेज पाने के लिए, उस वैल्यू को अगले कॉल के pageToken क्वेरी पैरामीटर में पास करें. जब nextPageToken खाली होता है, तो कोई और पेज नहीं होता.

उदाहरण के लिए, पिछले रिस्पॉन्स के टोकन का इस्तेमाल करके, गड़बड़ियों का अगला पेज देखने के लिए:

curl -X GET \
  -H "content-type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors?pageToken=cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj"

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

डेटासेट में नया डेटा अपलोड करना

डेटासेट बनाने और शुरुआती डेटा को अपलोड करने के बाद, डेटासेट की स्थिति STATE_COMPLETED पर सेट हो जाती है. इसका मतलब है कि डेटासेट आपके ऐप्लिकेशन में इस्तेमाल किए जाने के लिए तैयार है. डेटासेट के state का पता लगाने के लिए, डेटासेट पाना देखें.

डेटासेट का नया वर्शन बनाने के लिए, डेटासेट में नया डेटा भी अपलोड किया जा सकता है. नया डेटा अपलोड करने के लिए, उसी प्रोसेस का इस्तेमाल करें जिसका इस्तेमाल आपने Cloud Storage से डेटा अपलोड करने या फ़ाइल से डेटा अपलोड करने के लिए किया था. साथ ही, अपलोड करने के लिए नया डेटा तय करें.

अगर नया डेटा अपलोड हो जाता है, तो:

  • डेटासेट के नए वर्शन की स्थिति STATE_COMPLETED पर सेट है.

  • नया वर्शन, "चालू" वर्शन बन जाता है और इसका इस्तेमाल आपके ऐप्लिकेशन में किया जाता है.

अगर अपलोड करने में कोई गड़बड़ी होती है, तो:

  • डेटासेट के नए वर्शन की स्थिति, इनमें से किसी एक पर सेट होती है:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED
  • डेटासेट के सही तरीके से काम करने वाला पिछला वर्शन "चालू" वर्शन के तौर पर ही रहता है और वह वर्शन होता है जिसे आपके ऐप्लिकेशन में इस्तेमाल किया जाता है.