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

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

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

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

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

בדרך כלל, משתמשים בקבוצות של נכסים כדי לאחסן נתונים שלא יפוג תוקפם ושלא צריך להגדיר אותם בתוך הקוד של proxy ל-API. אפשר לגשת לנתונים של קבוצת נכסים בכל מקום בשרת 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 והיקף ארגוני:

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

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

ב-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"
    }
  ]
}

מידע נוסף מופיע במאמר בנושא 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

מידע נוסף מופיע במאמר בנושא 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 שבו יש גישה למשתני זרימה: במדיניות, בזרימות, בקוד 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. מעבד ההודעות טוען את קבוצת הנכסים שהורדה ומאפשר לשרתי proxy להפעיל אותה.