Label instances

‫MySQL   |  PostgreSQL   |  SQL Server

בדף הזה מוסבר על תוויות. במאמר הזה מוסבר איך ליצור מופע עם תוויות, איך להוסיף, לעדכן ולהסיר תוויות ואיך להשתמש בתוויות בחיפושים.

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

תמיד מוסיפים תוויות כצמדי מפתח/ערך:

{
 "userLabels": {
    "track": "production",
    "location": "western-division"
    "billing-code": "34802",...
 }

שינוי התוויות לא משפיע על הביצועים של מופע Cloud SQL.

מידע נוסף זמין במאמרים מהן תוויות? ודרישות לשימוש בתוויות.

הגבלות

• אפשר להקצות עד 64 תוויות לכל מופע.

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

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

יצירת מופעים עם תוויות

כשיוצרים מכונה חדשה באמצעות ה-CLI של gcloud או ה-API, אפשר להוסיף לה תוויות.

gcloud

כשיוצרים את המופע, כוללים את הדגל ‎ `--labels` ‎, ואחריו רשימה מופרדת בפסיקים של צמדי מפתח/ערך של תוויות. כדי לכלול תוויות, צריך להשתמש בגרסת הבטא של פקודת היצירה.

לדוגמה:

gcloud beta sql instances create ... --labels track=production,billing-code=34802

Terraform

כשיוצרים מופע עם תווית, משתמשים במשאב של Terraform:

resource "google_sql_database_instance" "default" {
  name             = "sqlserver-instance-labels"
  region           = "us-central1"
  database_version = "SQLSERVER_2019_STANDARD"
  root_password    = "INSERT-PASSWORD-HERE"
  settings {
    tier = "db-custom-2-7680"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
}

החלה של השינויים

כדי להחיל את ההגדרות של Terraform בפרויקט ב- Google Cloud , מבצעים את השלבים בקטעים הבאים.

הכנת Cloud Shell

1. מפעילים את Cloud Shell.

2. מגדירים את פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform. Google Cloud

   תצטרכו להריץ את הפקודה הזו רק פעם אחת לכל פרויקט, ותוכלו לעשות זאת בכל ספרייה.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. אם אתם עוקבים אחרי המדריך, תוכלו להעתיק את הקוד לדוגמה בכל קטע או שלב.

   מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

   לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
4. שומרים את השינויים.
5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה.

   terraform init

   אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:

   terraform init -upgrade

החלה של השינויים

1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:

   terraform apply

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

3. פותחים את Google Cloud הפרויקט כדי לראות את התוצאות. במסוף Google Cloud , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

הערה: בדרך כלל הנחת העבודה בדוגמאות של Terraform היא שממשקי ה-API הנדרשים מופעלים ב Google Cloud פרויקט.

מחיקת השינויים

כדי למחוק את השינויים:

1. כדי להשבית את ההגנה מפני מחיקה, בקובץ התצורה של Terraform מגדירים את הארגומנט deletion_protection לערך false.

   deletion_protection =  "false"

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform המעודכנות:

   terraform apply

3. כדי להסיר משאבים שהוחלו בעבר על הגדרות Terraform, מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה:

   terraform destroy

curl

ב-API, במהלך בקשת ה-POST להוספת מופע חדש, מוסיפים את המאפיין userLabels בגוף הבקשה כדי להחיל תוויות על המופע החדש. לדוגמה, גוף הבקשה שלכם ליצירת מופע מכיל את התוויות הבאות:

          "settings": {"tier":"db-custom-2-7680",
                       "userLabels": {"track": "production",
                                      "location": "western-division",
                                      "billing-code": "34802"},
          

הוספה או עדכון של תוויות במופע קיים

console

1. נכנסים לדף Cloud SQL Instances במסוף Google Cloud .

   כניסה לדף Cloud SQL Instances

2. מסמנים את תיבות הסימון לצד המשאבים שרוצים להוסיף להם תווית.

3. לוחצים על Show Info Panel (הצגת חלונית המידע) בפינה הימנית העליונה כדי להרחיב את העמודה labels (תוויות).

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

5. שומרים את השינויים.

gcloud

כדי לעדכן או להוסיף תוויות במופע קיים, משתמשים בפקודת המשנה patch (גרסת בטא):

gcloud beta sql instances patch [INSTANCE_NAME] --update-labels [KEY1]=[VALUE1]...

לדוגמה:

gcloud beta sql instances patch my-instance --update-labels track=production,billing-code=34802

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

rest v1

כדי להוסיף או לעדכן תוויות, משתמשים בשיטה PATCH:

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

• ‫project-id: מזהה הפרויקט
• ‫instance-id: מזהה המכונה
• ‫label-name-1: שם התווית
• ‫value-1: הערך של label-name-1
• ‫label-name-2: שם התווית
• ‫value-2: הערך של label-name-2

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

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

תוכן בקשת JSON:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

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

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

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

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

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

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

‫rest v1beta4

כדי להוסיף או לעדכן תוויות, משתמשים בשיטה PATCH:

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

• ‫project-id: מזהה הפרויקט
• ‫instance-id: מזהה המכונה
• ‫label-name-1: שם התווית
• ‫value-1: הערך של label-name-1
• ‫label-name-2: שם התווית
• ‫value-2: הערך של label-name-2

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

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

תוכן בקשת JSON:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

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

הסרת תווית

console

1. נכנסים לדף Cloud SQL Instances במסוף Google Cloud .

   כניסה לדף Cloud SQL Instances

2. מסמנים את תיבות הסימון לצד המשאבים שרוצים להסיר מהם את התוויות.

3. לוחצים על הצגת חלונית המידע כדי להרחיב את העמודה 'תוויות'.

4. לוחצים על הסמל X לצד כל התוויות שרוצים להסיר.

5. שומרים את השינויים.

gcloud

באמצעות ה-CLI של gcloud, מריצים את פקודת המשנה patch (גרסת בטא) עם הדגל --remove-labels:

gcloud beta sql instances patch [INSTANCE_NAME] --remove-labels [LABEL1],[LABEL2]

אם תספקו שם תווית שלא קיים, לא תוחזר שגיאה.

rest v1

כדי להסיר תווית באמצעות ה-API, מגדירים את הערך שלה ל-null:

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

• ‫project-id: מזהה הפרויקט
• ‫instance-id: מזהה המכונה
• ‫label-name: שם התווית

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

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

תוכן בקשת JSON:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

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

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

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

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

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

‫rest v1beta4

כדי להסיר תווית באמצעות ה-API, מגדירים את הערך שלה ל-null:

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

• ‫project-id: מזהה הפרויקט
• ‫instance-id: מזהה המכונה
• ‫label-name: שם התווית

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

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

תוכן בקשת JSON:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

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

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

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

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

סינון חיפושים של מופעים באמצעות תוויות

אפשר לסנן את התוצאות של רשימת המופעים לפי תוויות באמצעות ה-CLI של gcloud או ה-API.

gcloud

ב-gcloud, שולחים בקשת list ומשתמשים בדגל --filter. כדי לסנן לפי תוויות, משתמשים בתחביר labels.[KEY]:[VALUE]. לדוגמה, אם רוצים לסנן לפי תווית billing-code עם ערך של 34802, אפשר להריץ את הפקודה הבאה:

gcloud beta sql instances list --filter='labels.billing-code:34802'

אם רוצים לסנן לפי קיום של תווית, בלי קשר לערך שלה:

gcloud beta sql instances list --filter='labels:billing-code'

לתיעוד מלא על תחביר המסננים ב-CLI של gcloud, אפשר לעיין בתיעוד של gcloud topic filters.

curl

ב-API, שולחים בקשה לרשימה עם פרמטר שאילתה filter בקידוד כתובת URL:

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

לדוגמה:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

אם כוללים שני ערכי תוויות עם רווח (מקודד) ביניהם, שניהם צריכים להיות true כדי שמופע יוחזר (פעולת AND). אפשר גם לציין במפורש את האופרטורים AND, OR ו-NOT. לדוגמה:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

המאמרים הבאים

• מידע נוסף על ייצוא נתוני חיוב ל-BigQuery
• מידע נוסף על סינון באמצעות כלי gcloud