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

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

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

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

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

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

datasets एंडपॉइंट पर 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 या किसी लोकल फ़ाइल से डेटासेट में डेटा अपलोड करें.

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

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

Cloud Storage से अपने डेटासेट में डेटा अपलोड करने के लिए, datasets एंडपॉइंट को 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

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