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

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

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.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 של מערך הנתונים, משתמשים בקבלת מערך נתונים. לדוגמה, בזמן עיבוד הנתונים, הערך של 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

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