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

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

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 לנקודת הקצה (endpoint) של 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 מכיל הודעה אחת שמתארת את השגיאה. עם זאת, הודעת שגיאה אחת לא בהכרח מספקת מספיק מידע כדי לזהות ולתקן את הבעיות.

כדי לקבל מידע מלא על השגיאה, צריך להפעיל את fetchDatasetErrors API. ה-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

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