יצירת מערך נתונים

יצירת מערך נתונים היא תהליך שכולל שני שלבים:

1. שולחים בקשה ליצירת מערך הנתונים.

2. שולחים בקשה להעלאת נתונים למערך הנתונים.

אחרי ההעלאה הראשונית של הנתונים, אפשר להעלות נתונים חדשים למערך הנתונים כדי ליצור גרסה חדשה של מערך הנתונים.

יצירת מערך הנתונים

יוצרים מערך נתונים על ידי שליחת בקשת POST לנקודת הקצה datasets:

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 או מקובץ מקומי.

פעולת ההעלאה היא אסינכרונית. אחרי שמעלים את הנתונים, המערכת מעכלת ומעבדת אותם. כלומר, צריך לשלוח בקשת HTTP GET כדי לעקוב אחרי מצב מערך הנתונים ולקבוע מתי הוא מוכן לשימוש או אם היו שגיאות. מידע נוסף זמין במאמר בנושא קבלת סטטוס עיבוד הנתונים.

העלאת נתונים מ-Cloud Storage

כדי להעלות מ-Cloud Storage למערך הנתונים, שולחים בקשת POST לנקודת הקצה datasets, שכוללת גם את מזהה מערך הנתונים:

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

בגוף הבקשה בפורמט JSON:

• משתמשים ב-inputUri כדי לציין את נתיב הקובץ למשאב שמכיל את הנתונים ב-Cloud Storage. הנתיב הזה הוא מהצורה 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"
}

העלאת נתונים מקובץ

כדי להעלות נתונים מקובץ, שולחים בקשת HTTP POST לנקודת הקצה datasets שכוללת גם את מזהה מערך הנתונים::

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

קבלת סטטוס עיבוד הנתונים

פעולת ההעלאה היא אסינכרונית. כלומר, אחרי שהקריאה ל-API להעלאת הנתונים למערך הנתונים מוחזרת, צריך לבצע סקר למערך הנתונים כדי לקבוע אם ההטמעה והעיבוד של הנתונים הצליחו או נכשלו.

כדי לקבוע את state של מערך הנתונים, משתמשים ב-Get a dataset. לדוגמה, בזמן העיבוד של הנתונים, הערך של 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 מכיל הודעה אחת שמתארת את השגיאה. עם זאת, הודעת שגיאה אחת לא תמיד מספקת מספיק מידע כדי לזהות ולתקן את הבעיות.

כדי לקבל מידע מלא על השגיאה, צריך לשלוח קריאה ל-API של fetchDatasetErrors. ה-API הזה מחזיר את כל השגיאות בעיבוד הנתונים שמשויכות למערך נתונים:

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. המערך הזה מכיל עד 50 שגיאות מסוג Status לכל שיחה, ותומך בעד 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

• הגרסה הקודמת של מערך הנתונים שנוצרה בהצלחה נשארת הגרסה 'הפעילה' והיא הגרסה שבה נעשה שימוש באפליקציה.