אחזור של מערך נתונים

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

מידע על גרסאות של מערכי נתונים

אחרי העלאת הנתונים, הסטטוס של מערך הנתונים מוגדר ל-STATE_COMPLETED והוא הופך לגרסה הפעילה. כלומר, מערך הנתונים מוכן לשימוש באפליקציה. כדי לקבוע את הערך של state של מערך הנתונים, אפשר לרשום את כל מערכי הנתונים או לקבל מערך נתונים ספציפי.

אפשר להעלות נתונים חדשים למערך הנתונים כדי ליצור גרסה חדשה של מערך הנתונים:

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

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

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

הצגת רשימה של כל מערכי הנתונים

כדי לקבל רשימה של כל מערכי הנתונים, שולחים בקשת HTTP GET לנקודת הקצה list datasets:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

הבקשה הזו מחזירה מידע על הגרסה האחרונה של כל מערכי הנתונים, ללא קשר לכך שהגרסה הזו היא הגרסה הפעילה. אם רוצים להציג רק את הגרסה הפעילה של כל קבוצת נתונים, צריך לצרף לבקשה את פרמטר השאילתה tag=active:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets?tag=active

לדוגמה, הקריאה הזו מחזירה מידע על הגרסה העדכנית של כל מערכי הנתונים:

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"

הקריאה הזו מחזירה תשובה בפורמט:

{
  "datasets": [
    {
      "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e8a9e4f9fc46",
      "displayName": "My Test Dataset",
      "versionId": "5fb34e-1405-4ecd-8f81-31f1c07",
      "usage": [
        "USAGE_DATA_DRIVEN_STYLING"
      ],
      "gcsSource": {
        "inputUri": "gs://mybucket/my.csv",
        "fileFormat": "FILE_FORMAT_CSV"
      },
      "createTime": "2023-03-24T14:47:37.308977Z",
      "updateTime": "2023-03-24T14:48:05.053114Z",
      "versionCreateTime": "2023-03-24T14:48:05.053114Z",
      "status": {
        "state": "STATE_COMPLETED"
      }
    },
    {
      "name": "projects/PROJECT_NUMBER_OR_ID/datasets/2c8ae479-96704-89c6435ca959",
      "displayName": "My Other Test Dataset",
      "versionId": "0d2e3-b9da-47cc-819f-7ac67562",
      "usage": [
        "USAGE_DATA_DRIVEN_STYLING"
      ],
      "localFileSource": {
        "fileFormat": "FILE_FORMAT_CSV"
      },
      "createTime": "2023-03-24T14:41:52.579755Z",
      "updateTime": "2023-03-24T14:42:56.784122Z",
      "versionCreateTime": "2023-03-24T14:42:56.784122Z",
      "status": {
        "state": "STATE_COMPLETED"
      }
    }
  ]
}

קבלת מידע על מערך נתונים

כדי לקבל מידע על מערך נתונים ספציפי, שולחים בקשת HTTP GET לנקודת הקצה get dataset, שכוללת גם את המזהה של מערך הנתונים:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID

הבקשה הזו מחזירה מידע על הגרסה העדכנית ביותר של מערך הנתונים, ללא קשר לכך שהגרסה הזו היא הגרסה הפעילה. כדי לקבל מידע על הגרסה הפעילה של מערך הנתונים, צריך לצרף את התג @active לבקשה:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@active

לדוגמה:

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-e8a9e4f9fc46@active"

הבקשה הזו מחזירה תשובה בפורמט:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e8a9e4f9fc46",
  "displayName": "My Test Dataset",
  "versionId": "5fb34e-1405-4ecd-8f81-31f1c07",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "gcsSource": {
    "inputUri": "gs://mybucket/my.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2023-03-24T14:47:37.308977Z",
  "updateTime": "2023-03-24T14:48:05.053114Z",
  "versionCreateTime": "2023-03-24T14:48:05.053114Z",
  "status": {
    "state": "STATE_COMPLETED"
  }
}

הורדת מערך נתונים

כדי להוריד את הנתונים מהגרסה האחרונה של מערך נתונים, שולחים בקשת HTTP GET לנקודת הקצה download dataset, שכוללת גם את המזהה של מערך הנתונים:

הערה: יכול להיות שהגרסה האחרונה היא לא הגרסה הפעילה של מערך הנתונים.

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:download?alt=media

לדוגמה:

curl -X GET -L \
-H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
-H 'Authorization: Bearer $TOKEN' \
--output LOCAL_LOCATION_TO_OUTPUT \
"https://mapsplatformdatasets.googleapis.com/download/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e8a9e4f9fc46:download?alt=media"

בדוגמה הזו משתמשים באפשרות cURL --output כדי לציין את שם הקובץ שמכיל את הנתונים שהורדתם. לדוגמה, הדגל --output הבא מציין שצריך להוריד את מערך הנתונים לקובץ בשם myjson.json באותה ספרייה שבה הופעל הפקודה cURL:

--output myjson.json

לחלופין, אפשר להשתמש בדגל הבא כדי להוריד את הנתונים לקובץ myjson.json בספרייה /tmp:

--output /tmp/myjson.json