מדיניות SOAPMessageAuthentication

מוצג התיעוד של Apigee Edge.
נכנסים למסמכי התיעוד של Apigee X.
מידע

המדיניות SOAPMessageValidation יוצרת את הפעולות הבאות:

  • מאמת כל הודעת XML מול סכימות ה-XSD שלהן
  • אימות הודעות SOAP מול הגדרת WSDL
  • הגדרת הפורמט הנכון של הודעות JSON ו-XML

השם של המדיניות בממשק המשתמש הוא "SOAP Message Validation", אבל המדיניות מאמתת יותר מאשר רק הודעות SOAP. הקטע הזה מתייחס למדיניות כ'מדיניות לאימות הודעות'.

רכיב <MessageValidation>

הגדרת המדיניות בנושא אימות הודעות.

ערך ברירת מחדל מידע נוסף זמין בכרטיסייה מדיניות ברירת מחדל בהמשך
חובה? אופציונלי
סוג אובייקט מורכב
רכיב הורה לא רלוונטי
רכיבי צאצא <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

תחביר

הרכיב <MessageValidation> משתמש בתחביר הבא:

<MessageValidation
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All MessageValidation child elements are optional -->
    <DisplayName>policy_display_name</DisplayName>
    <Element namespace="element_namespace">element_to_validate</Element>
    <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
    <Source>message_to_validate</Source>
    <ResourceURL>validation_WSDL_or_XSD</ResourceURL>

</MessageValidation>

מדיניות ברירת מחדל

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

<MessageValidation continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
  <DisplayName>SOAP Message Validation-1</DisplayName>
  <Properties/>
  <Element namespace="http://sample.com">sampleObject</Element>
  <SOAPMessage/>
  <Source>request</Source>
  <ResourceURL>wsdl://SOAP-Message-Validation-1.wsdl</ResourceURL>
</MessageValidation>

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

מאפיין ברירת מחדל חובה? תיאור
name לא רלוונטי נדרש

השם הפנימי של המדיניות. הערך של המאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. האורך המקסימלי של הערך הוא 255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי להוסיף תווית למדיניות בכלי לעריכת שרת proxy של ממשק המשתמש לניהול, ולהשתמש בשם אחר בשפה טבעית.

continueOnError false אופציונלי צריך להגדיר את הערך 'False' כדי להחזיר שגיאה כשהמדיניות נכשלת. זו התנהגות צפויה ברוב סוגי המדיניות. הערך של הפרמטר הוא TRUE כדי שביצוע הפעולות יתבצע גם אחרי שמדיניות תיכשל.
enabled true אופציונלי כדי לאכוף את המדיניות צריך להגדיר את הערך True. מגדירים את המדיניות כ-"false" כדי "להשבית" את המדיניות. המדיניות הזו לא תיאכף גם אם היא תצורף לתהליך.
async   false הוצא משימוש המאפיין הזה הוצא משימוש.

דוגמאות

בדוגמאות הבאות אפשר לראות כמה מהדרכים שבהן אפשר להשתמש במדיניות בנושא אימות הודעות:

1: אימות XSD

אפשר להשתמש במדיניות בנושא אימות הודעות כדי לאמת את המטען הייעודי (payload) של בקשה בהודעת XML מול סכימת XSD.

  1. יוצרים קובץ משאבים חדש של XSD. לדוגמה, "note-schema.xsd":
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="note">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="to" type="xs:string"/>
            <xs:element name="from" type="xs:string"/>
            <xs:element name="heading" type="xs:string"/>
            <xs:element name="body" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  2. מוסיפים את המדיניות SOAP Message Validation (אימות הודעות SOAP) לתהליך המקדים של נקודת הקצה של שרת ה-proxy:
    1. צריך לציין את המיקום של קובץ משאבי ה-XSD באמצעות הרכיב <ResourceURL>. לדוגמה:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. מסירים את הרכיבים <SOAPMessage> ו-<Element> מהגדרת המדיניות.

    הגדרת המדיניות אמורה להיראות כך:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My XML Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <ResourceURL>xsd://note-schema.xsd</ResourceURL>
    </MessageValidation>
  3. שולחים בקשת POST לשרת ה-API של ה-API עם המטען הייעודי (payload) של ההודעה, כמו בדוגמה הבאה:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<note>
      <to>Fred Rogers</to>
      <from>Nick Danger</from>
      <heading>Greetings from my neighborhood</heading>
      <body>Just writing to say hello.</body>
    </note>'

    שימו לב שהכותרת Content-type מוגדרת כ-' application/xml'.

    אפשר גם ליצור קובץ נתונים למטען הייעודי (payload) ולהפנות אליו באמצעות פקודה שדומה לזו:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/note-payload.xml'

אתה אמור לקבל תגובה של HTTP 200. בהתאם לנקודת הקצה של היעד, יכול להיות שיתקבלו פרטים נוספים לגבי הבקשה. לדוגמה, אם משתמשים ב-http://httpbin.org/post כנקודת הקצה ומציינים פלט -v (דרגת מלל), התשובה אמורה להיות דומה לדוגמה הבאה:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

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

curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<note>
  <to>Fred Rogers</to>
  <from>Nick Danger</from>
  <heading>Greetings from my neighborhood</heading>
  <body>Just writing to say hello.</body>
  <badTag>Not good</badTag>
</note>'

אמורה להופיע שגיאת אימות.

2: אימות SOAP

אפשר להשתמש במדיניות לאימות הודעות כדי לאמת את המטען הייעודי (payload) של בקשת הודעת SOAP אל מול WSDL.

  1. יוצרים קובץ משאבים חדש של WSDL. לדוגמה, "example-wsdl.wsdl":
  2. מוסיפים את המדיניות SOAP Message Validation (אימות הודעות SOAP) לתהליך המקדים של נקודת הקצה של שרת ה-proxy:
    1. מגדירים את המאפיין version של האלמנט <SOAPMessage> לגרסה של פרוטוקול SOAP שרוצים לבצע אימות מולו. לדוגמה, "1.1":
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. מגדירים את הערך של האלמנט <Element> כרכיב שרוצים לאמת:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      <Element> מציין את הצאצא הראשון לרכיב <Body> שבמעטפת של בקשת ה-SOAP.

      מגדירים את המאפיין namespace למרחב השמות של הילד או הילדה.

    3. צריך לציין את המיקום של קובץ המשאבים של WSDL באמצעות הרכיב <ResourceURL>. לדוגמה:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    הגדרת המדיניות אמורה להיראות כך:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateSOAPRequest">
      <DisplayName>My SOAP Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <SOAPMessage version="1.1"/>
      <Element namespace="https://example.com/gateway">getID</Element>
      <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
    </MessageValidation>
  3. שולחים בקשת POST לשרת ה-API עם מעטפת ה-SOAP בתור המטען הייעודי (payload) של ההודעה, כמו בדוגמה הבאה:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:prox="https://example.com/gateway" xmlns:typ="https://example.com/gateway/types">
      <soapenv:Header/>
      <soapenv:Body>
        <prox:getID>
          <typ:MyType>
            <typ:ID>42</typ:ID>
          </typ:MyType>
        </prox:getID>
      </soapenv:Body>
    </soapenv:Envelope>'

    שימו לב שהכותרת Content-type מוגדרת כ-' application/xml'.

    אפשר גם ליצור קובץ נתונים למטען הייעודי (payload) ולהפנות אליו באמצעות פקודה שדומה לזו:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/soap-payload.xml'

אתה אמור לקבל תגובה של HTTP 200. בהתאם לנקודת הקצה של היעד, יכול להיות שיתקבלו פרטים נוספים לגבי הבקשה. לדוגמה, אם משתמשים ב-http://httpbin.org/post כנקודת הקצה, התשובה אמורה להיות דומה לזו:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

3: פורמט XML/JSON תקין

אפשר להשתמש במדיניות בנושא אימות הודעות כדי לוודא שהמטען הייעודי (payload) של הודעת JSON או XML תקין (לא זהה לאימות). המדיניות מבטיחה שהמבנה והתוכן יעמדו בסטנדרטים המקובלים, כולל:

  • יש רכיב בסיס אחד
  • אין תווים לא חוקיים בתוכן
  • האובייקטים והתגים מקוננים כראוי
  • יש התאמה בין תגי ההתחלה לתגי הסיום

כדי לבדוק אם יש מבנה תקין של מטען ייעודי (payload) של XML או של JSON:

  1. מוסיפים את המדיניות SOAP Message Validation (אימות הודעות ב-SOAP) לתהליך המקדים של נקודת הקצה של שרת ה-proxy.
  2. מסירים את הרכיבים <ResourceURL>, <SOAPMessage>, ו-<Element> מהגדרת המדיניות.

    הגדרת המדיניות אמורה להיראות כך:

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. שולחים בקשת POST לשרת ה-proxy של ה-API, כמו בדוגמה הבאה:
    curl -v -X POST -H 'Content-Type: application/json' http://my-test.apigee.net/v1/xsd-mock
      -d '{
    "note": {
      "to": "Fred Rogers",
      "from": "Nick Danger",
      "header": "Greetings from my neighborhood",
      "body": "Just writing to say hello."
      }
    }'

    שימו לב שהכותרת Content-type מוגדרת כ-'Application/json'.

    כדי לבדוק שהפורמט של קובץ XML תקין, צריך להשתמש ב-XML בתור המטען הייעודי (payload) של ההודעה ולהגדיר את Content-type לערך 'Application/xml'.

אתה אמור לקבל תגובה של HTTP 200. כששולחים מטען ייעודי (payload) של הודעה שלא מכיל XML או JSON בפורמט תקין, אמורה להופיע השגיאה steps.messagevalidation.Failed.

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הצאצא של <MessageValidation>.

<DisplayName>

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

הרכיב <DisplayName> משותף לכל כללי המדיניות.

ערך ברירת מחדל לא רלוונטי
חובה? אפשרות. אם משמיטים את הערך <DisplayName>, המערכת תשתמש בערך של המאפיין name של המדיניות
סוג מחרוזת
רכיב הורה <PolicyElement>
רכיבי צאצא אין

הרכיב <DisplayName> משתמש בתחביר הבא:

תחביר

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

דוגמה

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

לאלמנט <DisplayName> אין מאפיינים או רכיבי צאצא.

<Element>

מציין את הרכיב בהודעה שיש לאמת. זהו הצאצא הראשון שנמצא מתחת לרכיב <Body> במעטפה של בקשת ה-SOAP.

ערך ברירת מחדל sampleObject
חובה? אופציונלי
סוג מחרוזת
רכיב הורה <MessageValidation>
רכיבי צאצא אין

הרכיב <Element> משתמש בתחביר הבא:

תחביר

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

דוגמה 1

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

...
<Element namespace="https://example.com/gateway">getID</Element>
...

דוגמה 2

אפשר לציין יותר מרכיב אחד לאימות על ידי הוספת מספר רכיבי <Element>:

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

לרכיב <Element> יש את המאפיינים הבאים:

מאפיין ברירת המחדל חובה? תיאור
namespace "http://sample.com" אופציונלי מגדיר את מרחב השמות של הרכיב שיש לאמת.

<ResourceURL>

מזהה את סכימת XSD או את הגדרת WSDL שישמשו לאימות הודעת המקור.

ערך ברירת מחדל wsdl://display_name.wsdl
חובה? אופציונלי
סוג מחרוזת
רכיב הורה <MessageValidation>
רכיבי צאצא אין

הרכיב <ResourceURL> משתמש בתחביר הבא:

תחביר

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

דוגמאות

בקובץ XML:

...
<ResourceURL>xsd://note-schema.xsd</ResourceURL>
...

ל-WSDL:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

הערך של <ResourceURL> חייב להפנות לקובץ משאבים בשרת proxy ל-API. היא לא יכולה להפנות למשאבים חיצוניים ב-HTTP או HTTPS.

אם לא מציינים ערך ל-<ResourceURL>, ההודעה תישקל בפורמט JSON או XML בפורמט תקין אם הכותרת Content-type היא " application/json" או "Application/xml", בהתאמה.

ברכיב <ResourceURL> אין רכיבי צאצא או מאפיינים.

שימוש ב-XSD לאימות

אם המטען הייעודי של ה-XML שמאמת באמצעות המדיניות בנושא אימות הודעות מפנה לסכימה אחרת, צריך להוסיף את התחילית xsd לקובץ ה-XSD הכלול במאפיין schemaLocation.

הסכימה הבאה לדוגמה מורכבת מכמה התקני XSD:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:include schemaLocation="xsd://note-schema.xsd"/>
  <xs:include schemaLocation="xsd://letter-schema.xsd"/>
  <xs:include schemaLocation="xsd://user-schema.xsd"/>
</xs:schema>

שימוש באסימוני WSDL לאימות

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

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

<SOAPMessage>

המדיניות הזו מגדירה את גרסת ה-SOAP שלפיה יתבצע אימות של המדיניות בנושא אימות הודעות.

ערך ברירת מחדל לא רלוונטי
חובה? אופציונלי
סוג לא רלוונטי
רכיב הורה <MessageValidation>
רכיבי צאצא אין

הרכיב <SOAPMessage> משתמש בתחביר הבא:

תחביר

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

דוגמה

...
<SOAPMessage version="1.1"/>
...

לרכיב <SOAPMessage> יש את המאפיינים הבאים:

מאפיין ברירת המחדל חובה? תיאור
version אין אופציונלי גרסת SOAP שהמדיניות הזו משתמשת בה כדי לאמת הודעות SOAP.

הערכים החוקיים כוללים:

  • '1.1'
  • '1.2'
  • "1.1/1.2"

מידע נוסף זמין במאמר מ-SOAP/1.1 ל-SOAP בגרסה 1.2 ב-9 נקודות.

<Source>

מזהה את הודעת המקור שיש לאמת. הערך של הרכיב הזה הוא שם ההודעה שרוצים לאמת.

אם לא מגדירים את <Source>, ברירת המחדל של המדיניות הזו תהיה 'הודעה', שמתייחסת להודעת הבקשה המלאה (בתהליך הבקשה) או להודעת התשובה (בתהליך התגובה), כולל כל המטען הייעודי (payload). אפשר גם להגדיר במפורש את הערך 'בקשה' או 'תגובה' כך שיתייחס לבקשה או לתגובה.

ערך ברירת מחדל בקשה
חובה? אופציונלי
סוג מחרוזת
רכיב הורה <MessageValidation>
רכיבי צאצא אין

הרכיב <Source> משתמש בתחביר הבא:

תחביר

...
  <Source>message_to_validate</Source>
...

דוגמה

...
<Source>request</Source>
...

נוסף על 'הודעה', 'בקשה' ו'תגובה', אפשר להגדיר את הערך של <Source> לשם של כל הודעה בתהליך העבודה. אבל אם בחרת לעשות את זה, צריך ליצור הודעה מותאמת אישית עם השם הזה בתהליך לפני שהמדיניות תבוצע. אחרת, תתקבל הודעת שגיאה.

אם לא ניתן לפענח את הערך של <Source> בתהליך ההודעה או לשנות את הערך לסוג שאינו הודעה, תיתכן אחת מהאפשרויות הבאות:

  • אם הערך ריק: Edge יוצר את השגיאה steps.messagevalidation.SourceMessageNotAvailable.
  • אם סוג שאינו הודעה: Edge מציג את הודעת השגיאה steps.messagevalidation.NonMessageVariable.

לאלמנט <Source> אין מאפיינים או רכיבי צאצא.

קודי שגיאה

השגיאות שהוחזרו מהמדיניות של Edge הן בפורמט עקבי, כפי שמתואר בחומר העזר בנושא קוד שגיאה.

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

שגיאות בזמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד שגיאה סטטוס HTTP סיבה תיקון
steps.messagevalidation.SourceMessageNotAvailable 500

השגיאה הזו מתרחשת אם משתנה שצוין ברכיב <Source> של המדיניות הוא:

  • מחוץ להיקף (לא זמין בתהליך הספציפי שבו המדיניות מיושמת)
  • או
  • לא ניתן לפענח (אינו מוגדר)
steps.messagevalidation.NonMessageVariable 500

השגיאה הזו מתרחשת אם הרכיב <Source> במדיניות SOAPMessageAuthentication מוגדר למשתנה שאינו מסוג message.

משתנים של סוגי הודעות מייצגים את כל הבקשות והתגובות של HTTP. משתני הזרימה המובנים של Edge request, response ו-message הם מסוג הודעה. מידע נוסף על משתני הודעות זמין בחומר העזר בנושא משתנים.

steps.messagevalidation.Failed 500 השגיאה הזו מתרחשת אם המדיניות SOAPMessageValidation לא מאמתת את המטען הייעודי (payload) של הודעת הקלט מול סכימת XSD או ההגדרה של WSDL. זה יקרה גם אם בהודעת המטען הייעודי (payload) יש JSON או XML לא תקינים.

שגיאות בפריסה

השגיאות האלה יכולות להתרחש כשפורסים שרת proxy שכולל את המדיניות הזו.

שם השגיאה סיבה תיקון
InvalidResourceType הרכיב <ResourceURL> במדיניות SOAPMessageValidation מוגדר לסוג משאב שלא נתמך במדיניות.
ResourceCompileFailed סקריפט המשאב שמפנה לרכיב <ResourceURL> במדיניות SOAPMessageValidation מכיל שגיאה שמונעת את ההידור שלו.
RootElementNameUnspecified הרכיב <Element> במדיניות SOAPMessageValidation לא מכיל את השם של רכיב הבסיס.
InvalidRootElementName הרכיב <Element> במדיניות SOAPMessageValidation מכיל שם של רכיב בסיס שלא תואם לכללי ה-XML למתן שמות חוקיים לרכיבים.

סכימות

כל סוג מדיניות מוגדר באמצעות סכימת XML (.xsd). סכימות של מדיניות זמינות ב-GitHub.

נושאים קשורים