הגדרת ה-CLI של Universal Ledger

‫Universal Ledger CLI הוא ממשק שורת פקודה שנועד למטרות ניסוי, כדי להקל על שליחת עסקאות ואינטראקציה עם רשת Universal Ledger. לתרחישי שימוש בסביבת ייצור, מומלץ ליצור שילובים באמצעות ממשקי ה-API של Universal Ledger.

במדריך הזה מוסבר איך להתחיל להשתמש ב-CLI של Universal Ledger. בקישורים הבאים תוכלו ללמוד איך:

  • מורידים ומגדירים את ה-CLI של Universal Ledger.

  • יצירה וניהול של חשבונות באמצעות ה-CLI.

  • אפשר לבדוק פקודות אחרות שזמינות ב-CLI.

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

כדי להשלים את המדריך הזה, תצטרכו:

  • פרויקט ב- Google Cloud שבו מופעל Universal Ledger API.

  • תפקיד ב-IAM כמו roles/universalledger.networkUser, כדי שתוכלו לשלוח עסקאות ולשלוח שאילתות לגבי מצב החשבונות ברשת Universal Ledger.

  • חשבון Universal Ledger קיים שנוצר בשבילכם ברשת. אם אין לכם חשבון, תוכלו להיעזר במאמר בקשה לחשבון חדש.

הגדרת ה-CLI

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

מפעילים את Cloud Shell במסוף Google Cloud .

הפעלת Cloud Shell

מריצים את הפקודה הבאה כדי ליצור ספרייה שתכיל את קובצי התצורה של ה-CLI.

mkdir -p ~/.config/ul-cli

משיכת התמונה והגדרת השם החלופי

מריצים כל אחת מהפקודות הבאות כדי לשלוף את קובץ האימג' של Docker ב-ul-cli, להגדיר שם חלופי להרצת הקובץ הבינארי ולוודא שהקובץ הבינארי פועל:

docker pull us-central1-docker.pkg.dev/universal-ledger-artifacts/images/client/ul-cli:stable
alias ul-cli="docker run --rm -i --user $(id -u):$(id -g) \
    --volume /tmp:/tmp \
    --volume ~/.config/ul-cli:/home/.config/ul-cli \
    --volume ~/.config/gcloud:/home/.config/gcloud \
    --volume .:/workspace \
    --env HOME=/home \
    --workdir /workspace \
    us-central1-docker.pkg.dev/universal-ledger-artifacts/images/client/ul-cli:stable"
ul-cli --help

הגדרת ה-ul-cli

מריצים את הפקודה הבאה כדי להגדיר את ה-CLI.

ul-cli config setup projects/PROJECT_ID/locations/REGION/endpoints/NETWORK_NAME

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

  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו פועל Universal Ledger API.
  • ‫REGION: האזור של נקודת הקצה שאליה רוצים להגיע.
  • ‫NETWORK_NAME: שם הרשת שאיתה רוצים ליצור אינטראקציה.

אם אתם צריכים עזרה בבחירת נקודת קצה מתאימה, קראו את המאמר רשתות ומיקומים של Universal Ledger.

הפקודה הזו יוצרת את קובץ התצורה של ה-CLI ב-~/.config/ul-cli/config.yaml (ב-Linux וב-macOS).

ניהול חשבונות Universal Ledger

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

רישום של חשבון קיים

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

ul-cli accounts register \
    --alias ACCOUNT_ALIAS \
    --account-id ACCOUNT_ID \
    --key-name ACCOUNT_KMS_KEY

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

  • ‫ACCOUNT_ALIAS: מחרוזת קצרה שמשמשת באופן מקומי את ה-CLI כדי לזהות את החשבון הזה בהפעלות עתידיות של פקודות. לדוגמה: usd-operator, my-token-manager או test-user-account.
  • ‫ACCOUNT_ID: המזהה של חשבון Universal Ledger שנוצר בשבילכם.
  • ‫ACCOUNT_KMS_KEY: מזהה המשאב המלא של גרסת המפתח של Cloud KMS שמשמשת את החשבון הזה. החשבון חייב להיווצר באמצעות החלק הציבורי של גרסת המפתח הספציפית הזו. במאמר אחזור מזהה של משאב מוסבר מה הפורמט הצפוי.

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

ליצור חשבון חדש בשבילכם

אפשר ליצור חשבונות חדשים באמצעות פקודת המשנה ul-cli accounts create. לדוגמה, כדי ליצור חשבון משתמש חדש, אפשר להשתמש ב:

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --key-name NEW_ACCOUNT_KMS_KEY \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

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

  • ‫NEW_ACCOUNT_ALIAS: מחרוזת קצרה שמשמשת באופן מקומי את ה-CLI כדי לזהות את החשבון הזה בהפעלות עתידיות של פקודות.
  • ‫NEW_ACCOUNT_KMS_KEY: מזהה המשאב המלא של גרסת המפתח ב-Cloud KMS, שחשבון המשתמש החדש ישתמש בה.
  • ‫NEW_ACCOUNT_COMMENT: מחרוזת עם כל מידע רלוונטי שצריך לתעד בפנקס החשבונות שמשויך לחשבון המשתמש החדש. זהו ערך אטום שמאוחסן בפנקס החשבונות, אבל לא מפורש בדרך אחרת על ידי Universal Ledger. אחרי שיוצרים את השדה הזה, אי אפשר לשנות אותו וכל מי שיש לו גישה לרשת יכול לקרוא אותו.
  • ‫NEW_ACCOUNT_ROLES: רשימה מופרדת בפסיקים של תפקידים שיוקצו לחשבון המשתמש החדש. לדוגמה: payer, receiver, contract-creator או contract-participant.
  • ACCOUNT_MANAGER_ALIAS: השם החלופי של מנהל חשבון שנרשם או נוצר בעבר באמצעות ה-CLI.

הפעולה הזו תחתום על טרנזקציית CreateAccount ותשלח אותה בשם מנהל החשבון שצוין.

מריצים את ul-cli accounts create --help כדי לראות את האפשרויות הזמינות ליצירת סוגים אחרים של חשבונות.

יצירת חשבון חדש למישהו אחר

כדי ליצור חשבון למישהו אחר, צריך לבקש ממנו לשתף איתכם את המפתח הציבורי שלו ולשמור אותו בקובץ. באופן כללי, מומלץ להשתמש בפורמט קידוד PEM למפתחות. לדוגמה, אם מפתח החתימה משתמש בעקומה אליפטית P-256 עם תקציר SHA256, שומרים אותו בקובץ בשם pem_ec_p256_sha256.pub:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ/vWkd5wgakFbVD25k8WM9Ll6We+
c8RVDS0R4G8xetsmFjfNW/ZxwWeB86IvMjxY8ZsdU9+W7BL5YM6rUB5yCQ==
-----END PUBLIC KEY-----

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

ul-cli accounts create account \
    --alias NEW_ACCOUNT_ALIAS \
    --public-key "$(cat pem_ec_p256_sha256.pub)" \
    --key-format pem_ec_p256_sha256 \
    --comment "NEW_ACCOUNT_COMMENT" \
    --roles NEW_ACCOUNT_ROLES \
    --sender ACCOUNT_MANAGER_ALIAS

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

  • ‫NEW_ACCOUNT_ALIAS: מחרוזת קצרה שמשמשת באופן מקומי את ה-CLI כדי לזהות את החשבון הזה בהפעלות עתידיות של פקודות. אבל שימו לב: מכיוון שאין לכם את המפתח הפרטי של הכתובת, אתם לא יכולים לחתום על עסקאות או לשלוח אותן.
  • ‫NEW_ACCOUNT_COMMENT: מחרוזת עם כל מידע רלוונטי שצריך לתעד בפנקס החשבונות שמשויך לחשבון המשתמש החדש. זהו ערך אטום שמאוחסן בספר החשבונות, אבל לא מפורש בדרך אחרת על ידי Universal Ledger. אחרי שיוצרים את השדה הזה, אי אפשר לשנות אותו וכל מי שיש לו גישה לרשת יכול לקרוא אותו.
  • ‫NEW_ACCOUNT_ROLES: רשימה מופרדת בפסיקים של תפקידים שיוקצו לחשבון המשתמש החדש. לדוגמה: payer, receiver, contract-creator או contract-participant.
  • ACCOUNT_MANAGER_ALIAS: השם הסודי של מנהל חשבון שנרשם או נוצר בעבר באמצעות ה-CLI.

הפעולה הזו תחתום על טרנזקציית CreateAccount ותשלח אותה בשם מנהל החשבון שצוין.

הדגלים --public-key ו---key-format זמינים לכל פקודות המשנה של accounts create, כך שאפשר להשתמש בהם גם כדי ליצור סוגים אחרים של חשבונות. פורמטים נתמכים אחרים של מפתחות ציבוריים מפורטים בקטע KeyFormat במאמרי העזרה של Universal Ledger API.

הצגת רשימה של חשבונות מנוהלים

מריצים את הפקודה הבאה כדי לראות את כל החשבונות שרשומים באופן מקומי או שנוצרו באמצעות ה-CLI של Universal Ledger:

ul-cli accounts list

פקודות נוספות

אפשר להשתמש בדגל --help כדי לבדוק את כל הפקודות ופקודות המשנה האחרות שזמינות ב-CLI של Universal Ledger.

לדוגמה, כדי לראות את הפקודות הזמינות ברמה העליונה, מריצים את הפקודה:

ul-cli --help

זה כולל פקודות משנה לשליחת סוגים אחרים של טרנזקציות, כמו:

  • ‫accounts: כדי לרשום או ליצור חשבונות, ולבצע פעולות ניהול בחשבונות קיימים, כמו הוספה או הסרה של תפקידים, ושאילתות לגבי פרטי החשבון.
  • ‫contracts: לפריסה, להענקת הרשאות ולהפעלת שיטות בחוזים שניתנים לתכנות.
  • ‫issuance: למסלקה, כדי להגדיל או להקטין את מגבלת ההנפקה של מנהל טוקנים, ולבצע פעולות סליקה.
  • ‫tokens: למנהל אסימונים כדי להנפיק או לבטל אסימונים בחשבון משתמש.
  • ‫wallet: כדי להעביר סכום מהיתרה של חשבון משתמש לחשבון משתמש אחר.

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