יצירת מערך נתונים היא תהליך דו-שלבי:
שולחים בקשה ליצירת מערך הנתונים.
שולחים בקשה להעלאת נתונים למערך הנתונים.
אחרי ההעלאה הראשונית של הנתונים, תוכלו להעלות נתונים חדשים למערך הנתונים כדי ליצור גרסה חדשה של מערך הנתונים.
יצירת מערך הנתונים
כדי ליצור מערך נתונים, שולחים בקשת 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
הגרסה הקודמת של מערך הנתונים תישאר 'פעילה' והוא הגרסה שבה האפליקציה משתמשת.