הגדרת אינדקסים באמצעות ה-API בארכיטקטורת REST

בדף הזה מוסבר איך ליצור, למחוק ולרשום אינדקסים מורכבים במצב Datastore באמצעות API בארכיטקטורת REST של Datastore mode.

הכלי Google Cloud CLI מספק דרך נוחה לגשת ל-API בארכיטקטורת REST של מצב Datastore ולנהל את האינדקסים המורכבים. עם זאת, אתם יכולים לגשת ישירות ל-API בארכיטקטורת REST במצב Datastore כדי ליצור כלים משלכם לניהול האינדקסים המורכבים. לדוגמה, אפשר ליצור כלים לאוטומציה של הקצאת אינדקסים וניהול שלהם.

אימות והרשאה

כדי לגשת לשיטות של Firestore במצב Datastore API בארכיטקטורת REST שמופיעות בהמשך, צריך לאמת את הבקשה באמצעות אסימון גישה מסוג Google OAuth 2.0 עם אחת מההרשאות הבאות:

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

בדוגמאות הבאות של cURL ו-PowerShell נעשה שימוש בפקודה gcloud auth print-access-token כדי לאמת בקשות. למידע נוסף על קבלת אסימון גישה, אפשר לעיין במאמר בנושא שימוש ב-OAuth 2.0 כדי לגשת ל-Google APIs.

הרשאה

למשתמש, לקבוצה או לחשבון השירות המאומתים בבקשה צריכה להיות הרשאה לגשת לשיטות ה-API. כדי להרשות גישה לשיטות האינדוקס, צריך להקצות אחד מתפקידי ניהול הזהויות והרשאות הגישה (IAM) הבאים:

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

    • roles/owner
    • roles/editor
    • roles/datastore.owner
    • roles/datastore.indexAdmin

  • כדי לתת גישת קריאה לאינדקס בלבד (get ו-list), צריך להקצות אחד מהתפקידים הבאים:

    • roles/viewer
    • roles/datastore.user
    • roles/datastore.viewer

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

לפני שמתחילים

בדוגמאות של curl ו-PowerShell שבהמשך נעשה שימוש ב-Google Cloud CLI (Google Cloud CLI) כדי לאמת בקשות. כדי להריץ את הדוגמאות האלה באופן מקומי, צריך להתקין את Google Cloud CLI ולהפעיל אותו.

אפשר גם לגשת אל gcloud וcurl מGoogle Cloud Console באמצעות Cloud Shell.

מפעילים את Cloud Shell

יצירת אינדקס מורכב

כדי ליצור אינדקס מורכב חדש, משתמשים בשיטה projects.indexes.create.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט
  • ‫kind: סוג הישות לאינדקס
  • ‫include-ancestors: האם לכלול את ישויות האב באינדקס כדי לתמוך בשאילתות לגבי ישויות אב. האפשרויות הן NONE או ALL_ANCESTORS.
  • ‫property-name: הנכס לאינדקס, צריך לציין שני נכסים או יותר
  • ‫index-direction: סדר המיון של כל מאפיין, ASCENDING או DESCENDING

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://datastore.googleapis.com/v1/projects/project-id/indexes

גוף בקשת JSON: 

{
  "kind": "kind",
  "ancestor": "include-ancestors",
  "properties": [
      {
          "name": "property-name",
          "direction": "index-direction"
      },
      {
          "name": "property-name",
          "direction": "index-direction"
      }
  ]
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes" | Select-Object -Expand Content

APIs Explorer

מעתיקים את גוף הבקשה ופותחים את דף העזר של השיטה. החלונית של API Explorer תיפתח בצד שמאל של הדף. אפשר להשתמש בכלי הזה כדי לשלוח בקשות. מדביקים את גוף הבקשה בכלי הזה, ממלאים את כל שדות החובה ולוחצים על Execute.

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIDgxZGVhZDM0ZDc4MS1jMjJhLWQ1ZTQtYmMyNS1iYjY2NWVlZCQadGx1YWZlZAcSMXJoLXJleGVkbmktbmltZGERClIS",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
    "common": {
      "startTime": "2019-12-05T22:27:19.238Z",
      "operationType": "CREATE_INDEX",
      "state": "INITIALIZING"
    },
    "indexId": "CICAgJiUpoMK"
  }
}

קבלת סטטוס האינדקס

במצב Datastore, לכל אינדקס יש מזהה אינדקס ייחודי. אפשר להשתמש במזהה האינדקס הזה כדי לקבל את הסטטוס של אינדקס יחיד באמצעות ה-method‏ projects.indexes.get:

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט
  • ‫index-id: מזהה אינדקס מורכב

ה-method של ה-HTTP וכתובת ה-URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id"

PowerShell

מריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id" | Select-Object -Expand Content

APIs Explorer

פותחים את דף העזר של ה-method. החלונית של API Explorer תיפתח בצד שמאל של הדף. אפשר להשתמש בכלי הזה כדי לשלוח בקשות. ממלאים את כל שדות החובה ולוחצים על Execute.

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "projectId": "project-id",
  "indexId": "index-id",
  "kind": "Task",
  "ancestor": "NONE",
  "properties": [
    {
      "name": "done",
      "direction": "ASCENDING"
    },
    {
      "name": "priority",
      "direction": "ASCENDING"
    }
  ],
  "state": "READY"
}

מצב האינדקס

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

  • ‫CREATING: יצירת האינדקס נמצאת בתהליך.
  • ‫ALREADY_EXISTS: אי אפשר להשלים את הפעולה כי האינדקס הזה כבר קיים.
  • ‫ERROR: יצירת האינדקס נכשלה. צריך לתקן את הנתונים שגרמו לשגיאה, למחוק את האינדקס הזה ואז ליצור אותו מחדש.
  • ‫READY: יצירת האינדקס הושלמה. האינדקס מוכן לשימוש בשאילתות.

מחיקה של אינדקס מורכב

ה-method של ה-HTTP וכתובת ה-URL: 

DELETE https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

מריצים את הפקודה הבאה: 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id"

PowerShell

מריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes/index-id" | Select-Object -Expand Content

APIs Explorer

פותחים את דף העזר של ה-method. החלונית של API Explorer תיפתח בצד שמאל של הדף. אפשר להשתמש בכלי הזה כדי לשלוח בקשות. ממלאים את כל שדות החובה ולוחצים על Execute.

אמורים לקבל קוד סטטוס של הצלחה (2xx) ותגובה ריקה.

הצגת רשימה של כל האינדקסים המורכבים

כדי לראות את כל האינדקסים המורכבים במסד נתונים במצב Datastore, משתמשים בשיטה projects.indexes.list.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫project-id: מזהה הפרויקט

ה-method של ה-HTTP וכתובת ה-URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/indexes

כדי לשלוח את הבקשה אתם צריכים לבחור אחת מהאפשרויות הבאות:

curl

מריצים את הפקודה הבאה: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://datastore.googleapis.com/v1/projects/project-id/indexes"

PowerShell

מריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://datastore.googleapis.com/v1/projects/project-id/indexes" | Select-Object -Expand Content

APIs Explorer

פותחים את דף העזר של ה-method. החלונית של API Explorer תיפתח בצד שמאל של הדף. אפשר להשתמש בכלי הזה כדי לשלוח בקשות. ממלאים את כל שדות החובה ולוחצים על Execute.

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
 "indexes": [
  {
   "projectId": "project-id",
   "indexId": "CICAgOjXh4EK",
   "kind": "Task",
   "ancestor": "NONE",
   "properties": [
    {
     "name": "done",
     "direction": "ASCENDING"
    },
    {
     "name": "priority",
     "direction": "ASCENDING"
    }
   ],
   "state": "READY"
  },
  {
   "projectId": "project-id",
   "indexId": "CICAgNiroIEK",
   "kind": "Task",
   "ancestor": "NONE",
   "properties": [
    {
     "name": "due-date",
     "direction": "DESCENDING"
    },
    {
     "name": "priority",
     "direction": "ASCENDING"
    }
   ],
   "state": "CREATING"
  }
 ]
}