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

डेटासेट बनाने के लिए, दो चरणों वाली प्रोसेस अपनाई जाती है:

  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 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"
}

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

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

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