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

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

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

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

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

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

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

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

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

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

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 קבלה של מערך נתונים שגם היא כולל את המזהה של מערך הנתונים:

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"
  }
}

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

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

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

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