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

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

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

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