שימוש בקבוצות נכסים

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

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

לדוגמה:

• קבוצת הנכסים prod-env.properties מכילה את הנכס log-level=error
• קבוצת הנכסים test-env.properties מכילה את הנכס log-level=debug

באופן דומה, אפשר לאחסן מידע על ניתוב ספציפי לסביבה:

• קבוצת המאפיינים test-env.properties מכילה את המאפיין db-url=mydomain.test.datasource.com
• קבוצת המאפיינים prod-env.properties מכילה את המאפיין db-url=mydomain.prod.datasource.com

היקפי קבוצות נכסים

כשיוצרים קבוצת מאפיינים, אפשר להגדיר את ההיקף שלה לגרסה או לסביבה של proxy ל-API. אי אפשר להגדיר את ההיקף של קבוצת מאפיינים לארגון.

בטבלה הבאה מוסבר על ההתנהגות של קבוצות נכסים ועל ניהול שלהן עם proxy ל-API והיקף ארגוני:

היקף	התנהגות בזמן ריצה	ניהול
proxy ל-API	המאפיינים זמינים רק לגרסה של ה-proxy ל-API שמכילה את משאב קבוצת המאפיינים. אף proxy ל-API אחר או גרסה של אותו proxy לא יכולים לגשת לקבוצת המאפיינים הספציפית הזו.	אדמינים יכולים להשתמש ב-Apigee API‏ /resourcefiles או בממשק המשתמש כדי ליצור ולערוך קבוצות של מאפיינים. שמירת ה-proxy ל-API בממשק המשתמש תיצור גרסה חדשה, וקבוצת המאפיינים ששונתה תשויך רק לגרסה הזו.
סביבה	המאפיינים זמינים לכל הגרסאות של כל שרתי ה-API proxy בסביבה הזו. לפרוקסי של API בסביבות אחרות אין גישה לקבוצת המאפיינים הזו.	אדמינים יכולים להשתמש ב- /resourcefiles Apigee API או בממשק המשתמש כדי ליצור, להציג, לעדכן או למחוק קבוצות של מאפיינים בהיקף סביבה.

מגבלות על קבוצות נכסים

ב-Apigee יש מגבלות על קבוצות של מאפיינים, כמו שמתואר במאמר בנושא מגבלות. בנוסף, קובצי הגדרות מאפיינים צריכים להשתמש באותו תחביר כמו קובצי מאפיינים של Java, עם חריג אחד: אי אפשר להשתמש בסוגריים מסולסלים {} בקובצי הגדרות מאפיינים.

יצירת קבצים של קבוצת נכסים

בדרך כלל, שומרים את הערכים של קבוצת המאפיינים כצמדי שם/ערך בקובץ. קובצי הגדרות מאפיינים הם קובצי משאבים מסוג properties.

קובצי קבוצת מאפיינים תומכים באותו תחביר כמו קובצי מאפייני Java. לדוגמה, הם יכולים להכיל ערכי Unicode ולהשתמש בתווים # או ! כסמני הערות. יש יוצא מן הכלל אחד: אי אפשר להשתמש בסוגריים מסולסלים {} בקבצים של קבוצת מאפיינים.

חובה להוסיף את הסיומת .properties לשם של קובץ נכס. לדוגמה: מותר להשתמש ב-myconfig.my_key.properties, אבל אסור להשתמש ב-myconfig.my_key.

המבנה של הגדרת קבוצת מאפיינים הוא: property_set_name.property_name.properties שם קבוצת המאפיינים ושם המאפיין לא יכולים להכיל נקודות. לדוגמה: מותר להשתמש ב-myconfig.my_key.properties, אבל אסור להשתמש ב-myconfig.my.key.properties וב-my.config.my_key.properties.

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

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

אחרי שיוצרים קובץ של קבוצת נכסים, מעלים אותו ל-Apigee באמצעות ממשק המשתמש או API.

ניהול של קבוצות מאפיינים באמצעות ממשק המשתמש

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

הערה:

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

ניהול של קבוצות נכסים באמצעות ה-API

אפשר לנהל קבוצות של נכסים בהיקף של גרסה של proxy ל-API או של סביבה באמצעות ה-API, כמו שמתואר בקטעים הבאים.

יצירת קבוצות של נכסים באמצעות API

בקטעים הבאים מוסבר איך ליצור קבוצות של נכסים בהיקף של סביבה או של גרסה של שרת proxy ל-API באמצעות ה-API.

יצירת קבוצות של מאפיינים בהיקף של גרסה של proxy ל-API באמצעות API

הערה: אפשר להוסיף קבוצת מאפיינים בהיקף של תיקון קיים של שרת proxy ל-API רק אם התיקון לא נפרס. אחרי שפורסים תיקון של שרת proxy ל-API, אי אפשר לשנות אותו.

כדי ליצור קבוצת נכסים בהיקף של גרסה של proxy ל-API באמצעות ה-API:

1. יוצרים את קובץ קבוצת הנכסים.
2. מוסיפים את קובץ הגדרת המאפיינים לחבילת הגדרות של שרת proxy ל-API.
3. מעלים את החבילה באמצעות Create proxy ל-API או Update proxy ל-API revision API.

יצירת קבוצות של נכסים בהיקף של סביבה באמצעות ממשק ה-API

כדי להוסיף קבוצת מאפיינים בהיקף של סביבה באמצעות ה-API, יוצרים את קובץ קבוצת המאפיינים ואז מעלים אותו לסביבה בארגון באמצעות בקשת POST למשאב הבא: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles

הבקשה צריכה לכלול את הפרטים הבאים:

• מגדירים את פרמטר השאילתה name לשם של קבוצת הנכסים
• מגדירים את פרמטר השאילתה type לערך properties
• העברת התוכן של קובץ הגדרת הנכס כ-application/octet-stream או כ-multipart/form-data

הערה: כשמייבאים קובץ של קבוצת נכסים באמצעות ה-API, יכול להיות שיהיה צורך chmod את ההרשאות של הקובץ כדי שכלי הפיתוח (כמו curl) יוכל להעלות אותו.

בדוגמה הבאה, קבוצת מאפיינים בשם MyPropSet מיובאת מהקובץ /Users/myhome/myprops.properties:

curl -X POST "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles?name=MyPropSet&type=properties"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops.properties
  

‫$TOKEN מוגדר לאסימון הגישה שלכם ב-OAuth 2.0, כמו שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. למידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו, אפשר לעיין במאמר שימוש ב-curl.

בהמשך מופיעה דוגמה לתגובה.

{
  "name": "MyPropSet",
  "type": "properties"
}

מידע נוסף מופיע במאמר בנושא יצירת API של קובץ משאבים.

הצגת קבוצות של נכסים באמצעות ה-API

בקטעים הבאים מוסבר איך להציג קבוצות של נכסים בהיקף של סביבה באמצעות ה-API.

הצגת כל קבוצות הנכסים בהיקף של סביבה באמצעות ה-API

כדי להציג את כל קבוצות הנכסים שמוגדרות בסביבה באמצעות ה-API, שולחים בקשת GET למשאב הבא: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties

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

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties" \
  -H "Authorization: Bearer $TOKEN"
  

‫$TOKEN מוגדר לאסימון הגישה שלכם ב-OAuth 2.0, כמו שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. למידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו, אפשר לעיין במאמר שימוש ב-curl.

בהמשך מופיעה דוגמה לתגובה.

{
  "resourceFile": [
    {
      "name": "MyPropSet",
      "type": "properties"
    }
  ]
}

מידע נוסף מופיע במאמר List environment resource files API.

הצגת התוכן של קבוצת מאפיינים בהיקף של סביבה באמצעות ה-API

כדי להציג את התוכן של קבוצת מאפיינים בהיקף של סביבה באמצעות ה-API, שולחים בקשת GET למשאב הבא: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties/name

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

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet" \
  -H "Authorization: Bearer $TOKEN"
  

‫$TOKEN מוגדר לאסימון הגישה שלכם ב-OAuth 2.0, כמו שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. למידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו, אפשר לעיין במאמר שימוש ב-curl.

בהמשך מופיעה דוגמה לתגובה.

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

מידע נוסף מופיע במאמר List environment resource files API.

עדכון של קבוצות נכסים באמצעות ה-API

בקטעים הבאים מוסבר איך לעדכן קבוצות של מאפיינים בהיקף של גרסה או סביבה של שרת proxy ל-API באמצעות ה-API.

איך מעדכנים קבוצות של מאפיינים שמוגדרים לגרסה של proxy ל-API באמצעות ה-API

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

כדי לעדכן קבוצת מאפיינים שמוגדרת בהיקף של גרסה של proxy ל-API באמצעות ה-API:

1. מעדכנים את קובץ קבוצת המאפיינים.
2. מורידים את חבילת ההגדרות של ה-proxy ל-API באמצעות Get API proxy revision API עם האפשרויות הבאות:
   • מגדירים את פרמטר השאילתה format לערך bundle
   • מגדירים את הכותרת Accept ל-application/zip
3. מוסיפים את קובץ הגדרת המאפיינים לחבילת ההגדרות של ה-proxy ל-API.
4. מעלים את חבילת ההגדרות של ה-proxy ל-API באמצעות API‏ Update API proxy revision.

עדכון של קבוצות מאפיינים בהיקף של סביבה באמצעות ה-API

כדי לעדכן קבוצת מאפיינים שמוגדרת לסביבה באמצעות ה-API, מעדכנים את קובץ קבוצת המאפיינים ואז מעלים אותו לסביבה בארגון באמצעות שליחת בקשת PUT למשאב הבא: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

הבקשה צריכה לכלול את הפרטים הבאים:

• הגדרה של {type} לערך properties
• מגדירים את {name} לשם של קבוצת הנכסים שרוצים לעדכן.
• העברת התוכן של קובץ הגדרת הנכס כ-application/octet-stream או כ-multipart/form-data

הערה: כשמייבאים קובץ של קבוצת נכסים באמצעות ה-API, יכול להיות שיהיה צורך chmod את ההרשאות של הקובץ כדי שכלי הפיתוח (כמו curl) יוכל להעלות אותו.

בדוגמה הבאה, קבוצת המאפיינים MyPropSet מתעדכנת באמצעות התוכן של הקובץ /Users/myhome/myprops-revised.properties:

curl -X PUT "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops-revised.properties
  

‫$TOKEN מוגדר לאסימון הגישה שלכם ב-OAuth 2.0, כמו שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. למידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו, אפשר לעיין במאמר שימוש ב-curl.

בהמשך מופיעה דוגמה לתגובה.

{
  "name": "MyPropSet",
  "type": "properties"
}

מידע נוסף מופיע במאמר בנושא עדכון קובץ משאבים באמצעות API.

מחיקת קבוצות של נכסים באמצעות ה-API

בקטעים הבאים מוסבר איך למחוק קבוצות של מאפיינים בהיקף של גרסה או סביבה של proxy ל-API באמצעות ה-API.

מחיקת קבוצות של מאפיינים בהיקף של גרסה של proxy ל-API באמצעות ה-API

הערה: אפשר למחוק קבוצת מאפיינים בהיקף של גרסה של proxy ל-API אם היא לא נפרסה. אחרי שפורסים תיקון של שרת proxy ל-API, אי אפשר לשנות אותו.

כדי למחוק קבוצת נכסים שמוגדרת להיקף של גרסה של proxy ל-API באמצעות ה-API:

1. מורידים את חבילת ההגדרות של ה-proxy ל-API באמצעות Get API proxy revision API עם האפשרויות הבאות:
   • מגדירים את פרמטר השאילתה format לערך bundle
   • מגדירים את הכותרת Accept ל-application/zip
2. מוחקים את קובץ הגדרות המאפיינים מחבילת ההגדרות של שרת ה-proxy ל-API.
3. מעלים את חבילת ההגדרות של ה-proxy ל-API באמצעות API‏ Update API proxy revision.

מחיקת קבוצות של נכסים בהיקף של סביבה באמצעות ה-API

כדי למחוק קבוצת נכסים בהיקף של סביבה באמצעות ה-API, שולחים בקשת DELETE למשאב הבא: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

צריך להעביר את הפרטים הבאים עם הבקשה:

• הגדרה של {type} לערך properties
• מגדירים את {name} לשם של קבוצת המאפיינים שרוצים למחוק.

בדוגמה הבאה מוחקים את קבוצת המאפיינים MyPropSet:

curl -X DELETE https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet \
  -H "Authorization: Bearer $TOKEN"
  

‫$TOKEN מוגדר לאסימון הגישה שלכם ב-OAuth 2.0, כמו שמתואר במאמר איך מקבלים אסימון גישה מסוג OAuth 2.0. למידע על האפשרויות curl שבהן נעשה שימוש בדוגמה הזו, אפשר לעיין במאמר שימוש ב-curl.

בהמשך מופיעה דוגמה לתגובה.

{
  "name": "MyPropSet",
  "type": "properties"
}

מידע נוסף מופיע במאמר בנושא מחיקת קובץ משאבים באמצעות API.

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

אפשר לגשת לערכים של מאפיינים מוגדרים בכל מקום ב-proxy ל-API שבו יש גישה למשתני Flow: במדיניות, ב-Flows, בקוד JavaScript וכן הלאה.

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

propertyset.[property_set_name].[property_name]

כאשר:

• ‫property_set_name הוא שם הקובץ שהגדרתם (אם השתמשתם בממשק המשתמש) או הערך של פרמטר השאילתה name (אם השתמשתם ב-API).
• ‫property_name הוא שם הנכס. לדוגמה, אם קבוצת הנכסים מכילה את foo=bar, ‏ foo הוא שם הנכס ו-bar הוא הערך.

לדוגמה, במדיניות JavaScript, משתמשים בשיטה getVariable() כדי לקבל ערך מקבוצת מאפיינים:

context.getVariable('propertyset.property_set_name.property_name);

בדוגמה הבאה מוצג איך מקבלים את הערך של המאפיין foo בקבוצת המאפיינים שנקראת MyPropSet:

context.getVariable('propertyset.MyPropSet.foo);

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

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <Variable name="propertyset.MyPropSet.foo">
      <Pattern>{myVar}</Pattern>
   </Variable>
   <VariablePrefix>foobar</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

בדוגמה הזו, המדיניות קוראת את המשתנה מהמאפיין name ומקצה את הערך למשתנה ברכיב Pattern.

הקצאת הערך של מפתח של קבוצת מאפיינים באופן דינמי באמצעות מדיניות Assign Message

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

למשתמשי Apigee Hybrid

אם אתם משתמשים ב-Apigee hybrid, חשוב לשים לב לנקודות הבאות:

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