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

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

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

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

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

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

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

מידע נוסף על יצירת גרסה חדשה של קבוצת נתונים זמין במאמר העלאת נתונים חדשים לקבוצת הנתונים.

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

כדי להציג את כל מערכי הנתונים, שולחים בקשת HTTP מסוג GET לנקודת הקצה (endpoint) של רשימת מערכי הנתונים:

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 לנקודת הקצה (endpoint) 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 לנקודת הקצה (endpoint) של הורדת מערך הנתונים, שכוללת גם את המזהה של מערך הנתונים:

הערה: יכול להיות שהגרסה העדכנית היא לא הגרסה הפעילה של קבוצת הנתונים.

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