הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.
לעיון במסמכי התיעוד של
Apigee Edge
מדיניות PublishMessage מאפשרת לכם לפרסם מידע על זרימת ה-proxy ל-API בנושא Pub/Sub. שירות Pub/Sub של Google מאפשר לשירותים לתקשר באופן אסינכרוני, עם חביון נמוך משמעותית. מידע נוסף על Pub/Sub זמין במאמר מה זה Pub/Sub?. המידע שאתם רוצים לפרסם בנושא Pub/Sub יכול להיות טקסט מילולי או משתנה של זרימה. אפשר גם לציין שילוב של טקסט מילולי ומשתנים של זרימה באמצעות תבנית הודעה. Google Cloud
אם בקשת הפרסום מצליחה, Apigee מגדיר את משתנה הזרימה publishmessage.message.id לערך שמוחזר על ידי שרת Pub/Sub. מידע נוסף זמין במאמר בנושא משתני זרימה.
המדיניות הזו היא מדיניות רגילה ואפשר לפרוס אותה בכל סוג של סביבה. מידע על סוגי המדיניות והזמינות שלהם בכל סוג סביבה זמין במאמר סוגי מדיניות.
אימות ופריסת שרת proxy
כדי להפעיל את מדיניות PublishMessage, צריך אסימון אימות. עם זאת, אין רכיב <Authentication> מפורש בהגדרת המדיניות. צריך לפרוס את proxy ל-API כדי להשתמש באימות של Google, שמוסיף את אסימון האימות לבקשה מאחורי הקלעים. מידע על פריסת proxy ל-API שמשתמש באימות של Google זמין במאמר בנושא שלבי הפריסה.
צריך לפרוס את ה-proxy ל-API עם חשבון שירות שיש לו תפקיד עם ההרשאה pubsub.topics.publish. למידע נוסף על תפקידים בניהול זהויות והרשאות גישה (IAM) ב-Pub/Sub, אפשר לעיין במאמר הרשאות ותפקידים.
לחשבון השירות צריך להיות גם התפקיד roles/iam.serviceAccountTokenCreator כדי ליצור את האסימון לחשבון השירות של ה-proxy. מידע נוסף מופיע במאמר בנושא יצירת אסימונים בחשבון שירות.
<PublishMessage>
מציינת את מדיניות PublishMessage.
| ערך ברירת המחדל | לא רלוונטי |
| חובה? | חובה |
| סוג | סוג מורכב |
| רכיב אב | לא רלוונטי |
| רכיבי צאצא |
<Attributes><CloudPubSub><DisplayName><IgnoreUnresolvedVariables><Source><UseMessageAsSource> |
בטבלה הבאה מפורטים רכיבי המשנה של <PublishMessage>:
| רכיב צאצא | חובה? | תיאור |
|---|---|---|
<Attributes> |
אופציונלי | קבוצת מאפיינים לצירוף להודעת Pub/Sub. |
<CloudPubSub> |
חובה | רכיב האב של <Topic>. רכיב <Topic> מציין את נושא ה-Pub/Sub שבו רוצים לפרסם את ההודעה. |
<DisplayName> |
אופציונלי | שם מותאם אישית למדיניות. |
<IgnoreUnresolvedVariables> |
אופציונלי | המדיניות הזו קובעת אם העיבוד ייפסק אם Apigee ייתקל במשתנה לא פתור. |
<Source> |
אופציונלי | מציינים את ההודעה לפרסום בנושא Pub/Sub. האלמנט הזה הוא אופציונלי, אבל
חובה להשתמש ב-<Source> או ב-<UseMessageAsSource>.
|
<UseMessageAsSource> |
אופציונלי | מציינים את ההודעה לפרסום בנושא Pub/Sub. האלמנט הזה הוא אופציונלי, אבל
חובה להשתמש ב-<Source> או ב-<UseMessageAsSource>.
|
| רכיבי צאצא אחרים | ||
<Topic> |
חובה | רכיב צאצא של <CloudPubSub>. מציינים את נושא ה-Pub/Sub שאליו רוצים לפרסם את ההודעה. |
<Endpoint> |
אופציונלי | רכיב צאצא של <CloudPubSub>. מציינת את נקודת הקצה האזורית להודעות Pub/Sub כדי לתמוך במיקום נתונים מתקדם.
אם לא מציינים נקודת קצה, ברירת המחדל היא נקודת הקצה הגלובלית pubsub.googleapis.com:443. |
רכיב <PublishMessage> משתמש בתחביר הבא:
תחביר
<PublishMessage continueOnError="[true|false]" enabled="[true|false]" name="Publish-Message-1"> <DisplayName>DISPLAY_NAME</DisplayName> <Source>SOURCE_VALUE</Source> <Attributes> <Attribute> name=ATTRIBUTE_NAME>ATTRIBUTE_VALUE</Attribute> </Attributes> <CloudPubSub> <Topic>TOPIC_NAME</Topic> <Endpoint>REGIONAL_ENDPOINT</Endpoint> </CloudPubSub> <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables> </PublishMessage>
דוגמה – מקור
בדוגמה הבאה מוצגת הגדרת המדיניות <PublishMessage>:
<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1"> <DisplayName>Publish Message-1</DisplayName> <Source>this is a message template {flow-variable1}</Source> <CloudPubSub> <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic> </CloudPubSub> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </PublishMessage>
דוגמה – UseMessageAsSource
המדיניות הזו של <PublishMessage> מציינת את הרכיב UseMessageAsSource:
<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-2"> <UseMessageAsSource>request</UseMessageAsSource> <CloudPubSub> <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic> </CloudPubSub> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </PublishMessage>
דוגמה – מאפיינים
המדיניות הזו של <PublishMessage> מציינת את הרכיב Attributes:
<PublishMessage name="Publish-Message-3"> <Source>this is a message template {flow-variable1}</Source> <Attributes> <Attribute name='attr-name-0'>fixed-value</Attribute> <Attribute name='another-attribute-name'>{request.queryparam.attr1}</Attribute> <Attribute name='a-third-attribute-name'>{request.queryparam.attr2:default-value}</Attribute> </Attributes> <CloudPubSub> <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic> </CloudPubSub> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </PublishMessage>
דוגמה – המיקום של נתונים
המדיניות הזו של <PublishMessage> מציינת את הרכיב Endpoint:
<PublishMessage name="Publish-Message-3"> <Source>this is a message template {flow-variable1}</Source> <CloudPubSub> <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic> <Endpoint>pubsub.us.rep.googleapis.com:443</Endpoint> </CloudPubSub> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </PublishMessage>
לרכיב הזה יש את המאפיינים הבאים שמשותפים לכל המדיניות:
| מאפיין | ברירת מחדל | חובה? | תיאור |
|---|---|---|---|
name |
לא רלוונטי | חובה |
השם הפנימי של המדיניות. הערך של מאפיין אפשר להשתמש ברכיב |
continueOnError |
FALSE | אופציונלי | מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים. הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מאמרים קשורים:
|
enabled |
TRUE | אופציונלי | מגדירים את הערך true כדי לאכוף את המדיניות, או את הערך false כדי להשבית את המדיניות. המדיניות לא נאכפת גם אם היא עדיין משויכת לזרימה. |
async |
FALSE | הוצא משימוש | המאפיין הזה הוצא משימוש. |
הפניה לרכיב צאצא
בקטע הזה מתוארים רכיבי הבן של<PublishMessage>.
<Attributes>
מציינים את המאפיינים לצירוף להודעת Pub/Sub.
כל מאפיין הוא צמד מפתח/ערך. השם שמשויך למאפיין צריך להיות ייחודי. הערך של כל אחד מהם נקבע באופן דינמי בזמן הריצה באמצעות תבנית הודעה.
| ערך ברירת המחדל | לא רלוונטי |
| חובה? | חובה |
| סוג | String |
| רכיב אב |
<PublishMessage> |
| רכיבי צאצא | ללא |
רכיב <Attributes> משתמש בתחביר הבא:
תחביר
<Attributes> <Attribute name='NAME-1'>fixed-value</Attribute> <Attribute name='NAME-2'>{flow-variable}</Attribute> ... <Attribute name='NAME-N'>message template here {flow-variable:default-value}</Attribute> </Attributes>
דוגמה 1
בדוגמה הבאה מוגדר מאפיין יחיד עם ערך קבוע בהודעה בזמן הפרסום שלה:
<PublishMessage name="PM-with-one-attribute">
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
<Source>{request.queryparam.message}</Source>
<Attributes>
<Attribute name='my-attribute-1'>fixed-value</Attribute>
</Attributes>
<CloudPubSub>
<Topic>projects/{request.queryparam.project}/topics/{request.queryparam.topic}</Topic>
</CloudPubSub>
</PublishMessage>דוגמה 2
בדוגמה הבאה מוגדרים כמה מאפיינים בהודעה בזמן הפרסום שלה. הערכים של חלק מהמאפיינים נקבעים באופן דינמי בזמן הריצה:
<PublishMessage name="PM-with-multiple-attributes"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <Source>{my-assembled-message}</Source> <Attributes> <Attribute name='attr-0'>fixed-value</Attribute> <Attribute name='attr-1'>{flow-variable1}</Attribute> <Attribute name='attr-2'>fixed portion {flow-variable2:default-value}</Attribute> </Attributes> <CloudPubSub> <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic> </CloudPubSub> </PublishMessage>
<DisplayName>
אפשר להשתמש במאפיין הזה בנוסף למאפיין name כדי לתת למדיניות שם אחר, שנשמע יותר טבעי, ב-UI של עורך ה-proxy לניהול.
הרכיב <DisplayName> משותף לכל סוגי המדיניות.
| ערך ברירת המחדל | לא רלוונטי |
| חובה? | זה שינוי אופציונלי. אם לא מציינים את <DisplayName>, המערכת משתמשת בערך של מאפיין name של המדיניות. |
| סוג | String |
| רכיב אב | <PolicyElement> |
| רכיבי צאצא | ללא |
רכיב <DisplayName> משתמש בתחביר הבא:
תחביר
<PolicyElement> <DisplayName>POLICY_DISPLAY_NAME</DisplayName> ... </PolicyElement>
דוגמה
<PolicyElement> <DisplayName>My Validation Policy</DisplayName> </PolicyElement>
לרכיב <DisplayName> אין מאפיינים או רכיבי צאצא.
<Source>
מציינים את ההודעה לפרסום.
ההודעה יכולה להיות טקסט מילולי, משתנה של זרימת נתונים או שילוב של שניהם בצורה של תבנית הודעה.
| ערך ברירת המחדל | לא רלוונטי |
| חובה? | אופציונלי |
| סוג | String |
| רכיב אב |
<PublishMessage> |
| רכיבי צאצא | ללא |
רכיב <Source> משתמש בתחביר הבא:
תחביר
<Source>SOURCE</Source>
Example-1
בדוגמה הבאה, הודעת המקור מוגדרת לערך של משתנה הזרימה flow-var-1:
<Source>{flow-var-1}</Source>
Example-2
בדוגמה הבאה נעשה שימוש בתבנית הודעה כדי לפרסם הודעת JSON עם תוכן דינמי:
<PublishMessage name="PM-with-source-template"> <Source>{ "name": "value-1", "count": "{flow-variable1}", "action": "{flow-variable2}" }</Source> <Attributes> <Attribute name='content-type'>application/json</Attribute> </Attributes> <CloudPubSub> <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic> </CloudPubSub> </PublishMessage>
<CloudPubSub>
רכיב האב של <Topic>.
אפשר לפרסם רק בנושא אחד ב-Pub/Sub. לכן, אפשר להשתמש רק ברכיב <Topic> אחד בתוך הרכיב <CloudPubSub>.
| ערך ברירת המחדל | לא רלוונטי |
| חובה? | חובה |
| סוג | סוג מורכב |
| רכיב אב |
<PublishMessage> |
| רכיבי צאצא |
<Topic><Endpoint> |
רכיב <CloudPubSub> משתמש בתחביר הבא:
תחביר
<CloudPubSub> <Topic>TOPIC_NAME</Topic> <Endpoint>REGIONAL_ENDPOINT</Endpoint> </CloudPubSub>
דוגמה
בדוגמה הבאה מוצגת ההצהרה של רכיב <CloudPubSub>:
<CloudPubSub>
<Topic>projects/{my-project}/topics/{my-topic}</Topic>
<Endpoint>pubsub.us.rep.googleapis.com:443</Endpoint>
</CloudPubSub><Topic>
מציינים את נושא ה-Pub/Sub שאליו רוצים לפרסם את ההודעה <Source>.
צריך להשתמש בפורמט הבא: projects/project-id/topics/topic-name
| ערך ברירת המחדל | לא רלוונטי |
| חובה? | חובה |
| סוג | String |
| רכיב אב |
<CloudPubSub> |
| רכיבי צאצא | ללא |
רכיב <Topic> משתמש בתחביר הבא:
תחביר
<Topic>TOPIC_NAME</Topic>
דוגמה
בדוגמה הבאה מצוין נושא Pub/Sub לפרסום:
<Topic>projects/project-id-marketing/topics/topic-name-test1</Topic>
בדוגמה הזו, project-id-marketing הוא מזהה הפרויקט (Project ID) שלכם ו-topic-name-test1 הוא הנושא שבו צריך לפרסם את ההודעה. Google Cloud
<Endpoint>
מציינת את נקודת הקצה האזורית להעברת הודעות ב-Pub/Sub כדי לתמוך במיקום הנתונים.
| ערך ברירת המחדל | pubsub.googleapis.com:443 (נקודת קצה גלובלית) |
| חובה? | אופציונלי |
| סוג | String |
| רכיב אב |
<CloudPubSub> |
| רכיבי צאצא | ללא |
רכיב <Endpoint> משתמש בתחביר הבא:
תחביר
<Endpoint>pubsub.CONTROL_PLANE_LOCATION.rep.googleapis.com:443</Endpoint>CONTROL_PLANE_LOCATION הוא המיקום הפיזי שבו יאוחסנו נתוני מישור הבקרה של Apigee. רשימת המיקומים הזמינים של מישור הבקרה מופיעה במאמר מיקומי Apigee.
דוגמה
בדוגמה הבאה מוגדרת כתובת ה-URL של נקודת הקצה האזורית שבה צריך להשתמש להעברת הודעות ב-Pub/Sub בארה"ב כדי לתמוך במיקום הנתונים:
<Endpoint>pubsub.us.rep.googleapis.com:443</Endpoint>דוגמה – עם VPC Service Controls
בדוגמה הבאה מוגדרת כתובת ה-URL של נקודת הקצה האזורית שבה צריך להשתמש להעברת הודעות ב-Pub/Sub בארה"ב, כדי לתמוך במיקום הנתונים באמצעות VPC Service Controls:
<Endpoint>us-pubsub.googleapis.com:443</Endpoint><UseMessageAsSource>
מציינים את ההודעה לפרסום.
אפשר להשתמש בזה כחלופה לרכיב <Source>.
הערך צריך להיות שם של משתנה של תהליך שמתייחס להודעה, כמו
request, response או message. כשמציינים את רכיב, המדיניות משתמשת בתוכן ההודעה כהודעה לפרסום. כדאי להשתמש ברכיב הזה במקום ב-<Source> כשתוכן ההודעה הוא זרם אוקטטים שלא ניתן לייצג כמחרוזת, למשל תוכן מקובץ בינארי.
| ערך ברירת המחדל | לא רלוונטי |
| חובה? | אופציונלי |
| סוג | String |
| רכיב אב |
<PublishMessage> |
| רכיבי צאצא | ללא |
רכיב <UseMessageAsSource> משתמש בתחביר הבא:
תחביר
<PublishMessage name="PM-with-use-message-as-source"> <UseMessageAsSource>MESSAGE_NAME</UseMessageAsSource> <Attributes> <Attribute name='attr-1'>{flowvar1}</Attribute> </Attributes> <CloudPubSub> <Topic>projects/{flowvar1}/topics/{flowvar-topic}</Topic> </CloudPubSub> </PublishMessage>
Example-1
בדוגמה הבאה, המדיניות מציינת להשתמש בתוכן של הודעת הבקשה כמטען ייעודי (payload) להודעת Pub/Sub:
<PublishMessage name="PM-with-use-message-as-source"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <UseMessageAsSource>request</UseMessageAsSource> <Attributes> <Attribute name='attr-1'>{flowvar1}</Attribute> </Attributes> <CloudPubSub> <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic> </CloudPubSub> </PublishMessage>
<IgnoreUnresolvedVariables>
המדיניות הזו קובעת אם העיבוד ייפסק אם Apigee ייתקל במשתנה לא פתור.
| ערך ברירת המחדל | לא נכון |
| חובה? | אופציונלי |
| סוג | בוליאני |
| רכיב אב |
<PublishMessage>
|
| רכיבי צאצא | ללא |
מגדירים את הערך true כדי להתעלם ממשתנים שלא נפתרו ולהמשיך את העיבוד, אחרת מגדירים את הערך false. ערך ברירת המחדל הוא false.
ההגדרה של <IgnoreUnresolvedVariables> ל-true שונה מההגדרה של <PublishMessage>'s
continueOnError ל-true. אם מגדירים את continueOnError ל-true, מערכת Apigee מתעלמת מכל השגיאות, ולא רק משגיאות במשתנים.
רכיב <IgnoreUnresolvedVariables> משתמש בתחביר הבא:
תחביר
<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
דוגמה
בדוגמה הבאה, הערך של <IgnoreUnresolvedVariables> מוגדר ל-true:
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
משתנים בתהליך
משתני זרימה הם אובייקטים שמכילים נתונים ספציפיים וזמינים לכם בהקשר של זרימת proxy ל-API. המשתנים האלה שומרים מידע כמו פרטי מטען ייעודי (payload), נתיב כתובת ה-URL, כתובות IP ונתונים מהפעלת המדיניות. מידע נוסף על משתני זרימה זמין במאמר שימוש במשתני זרימה.
אם המדיניות PublishMessage מפרסמת בהצלחה בנושא Pub/Sub, Apigee מגדיר את משתנה הזרימה publishmessage.message.id לערך messageId שמוחזר על ידי שרת Pub/Sub. משתנה ה-Flow הוא מסוג string, והמשתנה זמין לכם החל מ-Proxy request flow. בהתאם לדרישה שלכם, אתם יכולים להשתמש במשתנה של התהליך במדיניות אחרת בהמשך התהליך. עם זאת, אם הפרסום נכשל, Apigee לא מגדיר את המשתנה publishmessage.message.id, וגישה למשתנה הזה תגרום לשגיאות.
מידע נוסף על סוגים שונים של משתני זרימה זמין במאמר חומר עזר בנושא משתני זרימה.
קודי שגיאה
בקטע הזה מתוארים קודי התקלה והודעות השגיאה שמוחזרים, ומשתני התקלה שמוגדרים על ידי Apigee כשמדיניות כזו מפעילה שגיאה. חשוב לדעת את המידע הזה אם אתם מפתחים כללי תקלות לטיפול בתקלות. מידע נוסף על שגיאות שקשורות למדיניות ועל טיפול בשגיאות
שגיאות זמן ריצה
השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.
| קוד תקלה | סטטוס HTTP | מטרה |
|---|---|---|
steps.publishmessage.PermissionDeniedError |
500 |
השגיאה הזו מתרחשת כשחשבון השירות של זמן הריצה לא יכול להתחזות לחשבון השירות של ה-proxy, או כשאין לחשבון השירות של ה-proxy הרשאה לפרסם בנושא. |
steps.publishmessage.ExecutionError |
500 |
השגיאה הזו מתרחשת אם הייתה שגיאה לא צפויה במהלך פרסום ההודעה ב-Pub/Sub. אפשר לראות את פרטי השגיאה בהודעת השגיאה. |
steps.publishmessage.MessageVariableNotMessageType |
500 |
השגיאה הזו מתרחשת אם אי אפשר לפענח את שם המשתנה שציינתם ב-UseMessageAsSource
או אם הוא לא סוג הודעה.
|
משתני תקלות
בכל פעם שמתרחשות שגיאות בהרצת מדיניות, מערכת Apigee יוצרת הודעות שגיאה. אפשר לראות את הודעות השגיאה האלה בתגובת השגיאה. לפעמים, הודעות שגיאה שנוצרות על ידי המערכת לא רלוונטיות בהקשר של המוצר שלכם. כדאי להתאים אישית את הודעות השגיאה בהתאם לסוג השגיאה כדי שההודעות יהיו משמעותיות יותר.
כדי להתאים אישית את הודעות השגיאה, אפשר להשתמש בכללי תקלות או במדיניות RaiseFault. מידע על ההבדלים בין כללי תקלות לבין מדיניות RaiseFault זמין במאמר FaultRules לעומת מדיניות RaiseFault.
צריך לבדוק את התנאים באמצעות הרכיב Condition גם בכללי השגיאה וגם במדיניות RaiseFault.
Apigee מספק משתני שגיאה שייחודיים לכל מדיניות, והערכים של משתני השגיאה מוגדרים כשמדיניות מפעילה שגיאות בזמן ריצה.
באמצעות המשתנים האלה, אפשר לבדוק תנאי שגיאה ספציפיים ולנקוט פעולות מתאימות. מידע נוסף על בדיקת תנאי שגיאה זמין במאמר יצירת תנאים.
| משתנים | כאשר: | דוגמה |
|---|---|---|
fault.name |
הערך fault.name יכול להתאים לכל אחת מהתקלות שמופיעות בטבלה שגיאות בזמן ריצה.
שם התקלה הוא החלק האחרון של קוד התקלה. |
fault.name Matches "UnresolvedVariable" |
publishmessage.POLICY_NAME.failed |
POLICY_NAME הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה. | publishmessage.publish-message-1.failed = true |