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

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

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 של משתמשים ב-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

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