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

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

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

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

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

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

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

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

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

מציגים את רשימת כל מערכי הנתונים על ידי שליחת בקשת 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 לנקודת הקצה 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"
  }
}

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

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