ניהול חבילות Java

ב-Artifact Registry אפשר לאחסן חבילות Java, לנהל את הגרסאות שלהן ולנהל אותן במאגרים בפורמט Maven באמצעות Maven או Gradle. אתם יכולים לפרסם ארטיפקטים של בנייה, לבדוק גרסאות וקבצים מאוחסנים, להגדיר חבילות כתלויות בפרויקט ולמחוק גרסאות שלא בשימוש.

אם רוצים להשתמש ב-sbt ככלי לבנייה של Scala ו-Java במקום Maven או Gradle, אפשר להשתמש בפלאגין sbt שנוצר על ידי הקהילה. במסמך הזה לא מוסבר איך להגדיר או להשתמש בלקוחות Scala.

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

1. אם מאגר היעד לא קיים, צריך ליצור מאגר חדש.
2. מוודאים שיש לכם את ההרשאות הנדרשות למאגר.
3. מוודאים שהגדרתם אימות. אם אתם משתמשים באסימון גישה, חשוב לרענן את האסימון לפני שמתחברים למאגר.
4. (אופציונלי) הגדרת ברירות מחדל לפקודות gcloud.

התפקידים הנדרשים

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

• כדי לראות חבילות או קבצים בחבילות: קורא Artifact Registry (roles/artifactregistry.reader)
• הורדה או התקנה של חבילות: קורא Artifact Registry (roles/artifactregistry.reader)
• כדי להוסיף חבילות למאגר: Artifact Registry Writer (roles/artifactregistry.writer)
• מחיקת חבילות: אדמין של מאגר Artifact Registry (roles/artifactregistry.repoAdmin)

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

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

הוספת חבילות

מצבי מאגר: רגיל

כדי להוסיף חבילות למאגר:

Maven

משתמשים בפקודות mvn deploy ו-mvn release כדי להוסיף חבילות למאגר.

כדי לפרוס בהצלחה פרויקט Maven שמפנה לפרויקט אב, הפרויקט צריך לכלול את ספק ה-Wagon של Artifact Registry בקובץ של תוספי ליבה, כפי שמתואר בהוראות האימות.

משתמשים ב-mvn deploy:deploy-file כדי להעלות ארטיפקטים שנבנו מחוץ ל-Maven.

לדוגמה, הפקודה הבאה פורסת את example/external.jar ואת קובץ הפרויקט example/pom.xml שלו במאגר us-central1-maven.pkg.dev/my-project/my-repo

mvn deploy:deploy-file \
-Durl=artifactregistry://us-central1-maven.pkg.dev/my-project/my-repo \
-DpomFile=example/pom.xml -Dfile=example/external.jar

הערה: אי אפשר להשתמש בפקודה mvn archetype אם משתמשים בה רק ממאגר Artifact Registry.

איך משלבים עם Cloud Build

Gradle

כדי לפרסם בהצלחה במאגר, קובץ build.gradle צריך לכלול קטע publications שבו מוגדרים הקבצים להעלאה.

משתמשים בפקודה gradle publish כדי להעלות חבילה למאגר.

צפייה בחבילות ובגרסאות

מצבי מאגר: רגיל, מרוחק

כדי לראות חבילות וגרסאות של חבילות באמצעות Google Cloud המסוף או gcloud:

המסוף

1. פותחים את הדף Repositories במסוף Google Cloud .

   פתיחת הדף Repositories

2. ברשימת המאגרים, לוחצים על המאגר המתאים.

   בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

3. לוחצים על חבילה כדי לראות את הגרסאות שלה.

gcloud

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

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

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

• ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
• ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אם הגדרתם מיקום ברירת מחדל, תוכלו להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

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

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

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

• ‫PACKAGE הוא המזהה של החבילה או המזהה המלא של החבילה.
• ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
• ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ משתמשים בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

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

מרכיב רשימת קבצים

מצבי מאגר: רגיל, מרוחק

אפשר להציג רשימה של קבצים במאגר, קבצים בכל הגרסאות של חבילה ספציפית או קבצים בגרסה ספציפית של חבילה.

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

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

gcloud artifacts files list

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

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

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

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

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

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

מחליפים את הערכים הבאים:

• ‫LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
• ‫PROJECT: Google Cloud מזהה הפרויקט. אם מזהה הפרויקט מכיל נקודתיים (:), כדאי לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
• ‫REPOSITORY: השם של המאגר שבו התמונה מאוחסנת.
• ‫PACKAGE: שם החבילה.
• ‫VERSION: גרסת החבילה.

דוגמאות

כדאי לעיין בפרטי החבילה הבאים:

• פרויקט: my-project
• מאגר: my-repo
• מיקום המאגר: us-west1
• חבילה: my-app

הפקודה הבאה מציגה רשימה של כל הקבצים במאגר my-repo במיקום us-west1 בתוך פרויקט ברירת המחדל:

‫

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

הפקודה הבאה מציגה רשימה של קבצים בגרסה 1.0 של החבילה.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

הורדת חבילות

מצבי מאגר: רגיל, מרוחק, וירטואלי

כדי להוריד ארטיפקט כחלק מה-build, צריך להגדיר את הארטיפקט כתלות.

Maven

1. מצהירים על החבילות שרוצים להוריד בקובץ pom.xml של הפרויקט. בדוגמה הבאה מוצהרת גרסה 1.0 של החבילה artifact כתלות.

   <dependencies>
       <dependency>
           <groupId>group</groupId>
           <artifactId>artifact</artifactId>
           <version>1.0</version>
       </dependency>
   </dependencies>
   

   מידע נוסף על יחסי תלות ב-Maven זמין במאמרים introduction to dependencies ו-dependency reference.

2. מבצעים Build לפרויקט Java.

   mvn compile
   

Gradle

1. מצהירים על החבילות שרוצים להוריד בקובץ build.gradle של הפרויקט. בדוגמה הבאה מוצהרת גרסה 1.0 של החבילה artifact כתלות חיצונית של קומפילציה.

   מידע נוסף על יחסי תלות ב-Gradle זמין במסמכי התיעוד של Gradle.

   dependencies {
       compile group: 'group', name: 'artifact', version: '1.0'
   }
   

2. מבצעים Build לפרויקט Java.

   gradle build
   

במאגרים רגילים, מורידים חבילה ישירות מהמאגר.

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

במאגר וירטואלי, מערכת Artifact Registry מחפשת את החבילה המבוקשת במאגרים במעלה הזרם.

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

לדוגמה, נניח שיש מאגר וירטואלי עם הגדרות העדיפות הבאות למאגרי upstream:

• ‫main-repo: העדיפות מוגדרת ל-100
• ‫secondary-repo1: העדיפות מוגדרת ל-80.
• ‫secondary-repo2: העדיפות מוגדרת ל-80.
• ‫test-repo: העדיפות מוגדרת ל-20.

ל-main-repo יש את ערך העדיפות הגבוה ביותר, ולכן המאגר הווירטואלי תמיד מחפש בו קודם.

העדיפות של secondary-repo1 ושל secondary-repo2 מוגדרת כ80. אם חבילה מבוקשת לא זמינה ב-main-repo, ‏ Artifact Registry מחפש אותה במאגרים האלה. מכיוון שלשניהם יש את אותו ערך עדיפות, מערכת Artifact Registry יכולה לבחור להציג חבילה מכל אחד מהמאגרים אם הגרסה זמינה בשניהם.

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

מחיקת חבילות וגרסאות

מצבי מאגר: רגיל, מרוחק

אתם יכולים למחוק חבילה ואת כל הגרסאות שלה, או למחוק גרסה ספציפית.

• אחרי שמוחקים חבילה, אי אפשר לבטל את הפעולה.
• במאגרים מרוחקים, רק העותק שבמטמון של החבילה נמחק. אין השפעה על מקור ה-upstream. אם מוחקים חבילה במטמון, Artifact Registry יוריד אותה וישמור אותה במטמון שוב בפעם הבאה שמאגר המידע יקבל בקשה לאותה גרסת חבילה.

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

כדי למחוק חבילה:

המסוף

1. פותחים את הדף Repositories במסוף Google Cloud .

   פתיחת הדף Repositories

2. ברשימת המאגרים, לוחצים על המאגר המתאים.

   בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

3. בוחרים את החבילה שרוצים למחוק.

4. לוחצים על מחיקה.

5. בתיבת הדו-שיח לאישור, לוחצים על מחיקה.

gcloud

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

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

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

• ‫PACKAGE הוא שם החבילה במאגר.
• ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
• ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אפשר להשתמש בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

הדגל --async גורם לפקודה לחזור באופן מיידי, בלי להמתין שהפעולה תסתיים.

כדי למחוק גרסאות של חבילה:

המסוף

1. פותחים את הדף Repositories במסוף Google Cloud .

   פתיחת הדף Repositories

2. ברשימת המאגרים, לוחצים על המאגר המתאים.

   בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

3. לוחצים על חבילה כדי לראות את הגרסאות שלה.

4. בוחרים את הגרסאות שרוצים למחוק.

5. לוחצים על מחיקה.

6. בתיבת הדו-שיח לאישור, לוחצים על מחיקה.

gcloud

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

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

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

• ‫VERSION הוא שם הגרסה שרוצים למחוק.
• ‫PACKAGE הוא שם החבילה במאגר.
• ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
• ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אפשר להשתמש בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

הדגל --async גורם לפקודה לחזור באופן מיידי, בלי להמתין שהפעולה תסתיים.

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

• מידע ולמידה על ניהול חבילות Node.js
• מידע על ניהול חבילות Python
• מידע ולמידה על ניהול קובצי אימג' של קונטיינרים
• הורדת קבצים ספציפיים בחבילה