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

אחרי שיוצרים מערך נתונים ומעלים אליו נתונים, אפשר להשתמש בבקשות 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