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

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

במדריך הזה מוסבר איך מתחילים להשתמש ב-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 בסביבה אחרת.

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

הפעלת Cloud Shell

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

mkdir -p ~/.config/ul-cli

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

docker pull us-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest
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-docker.pkg.dev/gcul-artifacts/images/client/ul-cli:latest"
ul-cli --help

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

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

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

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

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

הפקודה הקודמת תיצור קובץ בתיקייה

~/.config/ul-cli/config.yaml

עם ההגדרה שבה ישתמש ה-CLI ושתישמר על ידו.

ניהול חשבונות ב-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.

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

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

ul-cli accounts list

רוצה לנסות עוד פקודות?

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

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

ul-cli --help

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

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

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