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

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

  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 Object Viewer की भूमिका होनी चाहिए. इसके अलावा, उसके पास कोई ऐसी भूमिका भी हो सकती है जिसमें 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"
}

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

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

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