Chính sách XMLtoJSON

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. Thông tin

Nội dung

Chính sách này chuyển đổi thông báo từ định dạng ngôn ngữ đánh dấu có thể mở rộng (XML) sang Ký hiệu đối tượng JavaScript (JSON), cung cấp cho bạn một số lựa chọn để kiểm soát cách chuyển đổi thông báo.

Giả sử mục đích là chuyển đổi một phản hồi có định dạng XML thành một phản hồi có định dạng JSON, chính sách này sẽ được đính kèm vào một Luồng phản hồi (ví dụ: Phản hồi / ProxyEndpoint/PostFlow).

Giới thiệu

Trong một kịch bản dàn xếp điển hình, chính sách JSON sang XML trong luồng yêu cầu đến thường được ghép nối với chính sách XML sang JSON trong luồng phản hồi đi. Bằng cách kết hợp các chính sách theo cách này, bạn có thể hiển thị một API JSON cho các dịch vụ phụ trợ chỉ hỗ trợ XML một cách tự nhiên.

Đối với những trường hợp mà các API được nhiều ứng dụng khách sử dụng và có thể yêu cầu JSON hoặc XML, bạn có thể thiết lập định dạng phản hồi một cách linh hoạt bằng cách định cấu hình các chính sách JSON sang XML và XML sang JSON để thực thi có điều kiện. Hãy xem Các biến và điều kiện của luồng để biết cách triển khai trường hợp này.

Mẫu

Để biết thông tin chi tiết về cách chuyển đổi giữa JSON và XML, hãy xem bài viết Chuyển đổi giữa XML và JSON bằng Apigee: Những điều bạn cần biết.

<XMLToJSON name="ConvertToJSON">
  <Options>
  </Options>
  <OutputVariable>response</OutputVariable>
  <Source>response</Source>
</XMLToJSON>

Tham chiếu phần tử

Sau đây là các phần tử và thuộc tính mà bạn có thể định cấu hình trên chính sách này.

<XMLToJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">
    <DisplayName>XML to JSON 1</DisplayName>
    <Source>response</Source>
    <OutputVariable>response</OutputVariable>
    <Options>
        <RecognizeNumber>true</RecognizeNumber>
        <RecognizeBoolean>true</RecognizeBoolean>
        <RecognizeNull>true</RecognizeNull>
        <NullValue>NULL</NullValue>
        <NamespaceBlockName>#namespaces</NamespaceBlockName>
        <DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
        <NamespaceSeparator>***</NamespaceSeparator>
        <TextAlwaysAsProperty>true</TextAlwaysAsProperty>
        <TextNodeName>TEXT</TextNodeName>
        <AttributeBlockName>FOO_BLOCK</AttributeBlockName>
        <AttributePrefix>BAR_</AttributePrefix>
        <OutputPrefix>PREFIX_</OutputPrefix>
        <OutputSuffix>_SUFFIX</OutputSuffix>
        <StripLevels>2</StripLevels>
        <TreatAsArray>
            <Path unwrap="true">teachers/teacher/studentnames/name</Path>
        </TreatAsArray>
    </Options>
    <!-- Use Options or Format, not both -->
    <Format>yahoo</Format>
</XMLToJSON>

Thuộc tính <XMLtoJSON>

<XMLtoJSON async="false" continueOnError="false" enabled="true" name="XML-to-JSON-1">

Bảng sau đây mô tả những thuộc tính chung cho tất cả phần tử mẹ của chính sách:

&lt;DisplayName&gt; phần tử

Hãy sử dụng cùng với thuộc tính name để gắn nhãn chính sách trong phần trình chỉnh sửa proxy giao diện người dùng quản lý có tên ngôn ngữ tự nhiên khác.

<DisplayName>Policy Display Name</DisplayName>

Phần tử <Source>

Biến, yêu cầu hoặc phản hồi chứa thông báo XML mà bạn muốn chuyển đổi thành JSON.

Bạn phải đặt tiêu đề Content-type HTTP của thông báo nguồn thành application/xml, nếu không chính sách sẽ không được thực thi.

Nếu bạn không xác định <Source>, thì giá trị này sẽ được coi là thông báo (giải quyết yêu cầu khi chính sách được đính kèm vào một luồng yêu cầu hoặc phản hồi khi chính sách được đính kèm vào một luồng phản hồi).

Nếu không thể phân giải biến nguồn hoặc phân giải thành một loại không phải thông báo, thì chính sách sẽ gửi một lỗi.

<Source>response</Source>

Phần tử <OutputVariable>

Lưu trữ đầu ra của quá trình chuyển đổi định dạng XML sang JSON. Đây thường là giá trị giống như nguồn, tức là phản hồi XML thường được chuyển đổi thành phản hồi JSON.

Tải trọng của thông báo XML được phân tích cú pháp và chuyển đổi thành JSON, đồng thời tiêu đề Content-type HTTP của thông báo có định dạng XML được đặt thành application/json.

Nếu bạn không chỉ định OutputVariable, thì source sẽ được coi là OutputVariable. Ví dụ: nếu source là response, thì OutputVariable sẽ mặc định là response.

<OutputVariable>response</OutputVariable>

<Options> (Tuỳ chọn)

Các lựa chọn này giúp bạn kiểm soát quá trình chuyển đổi từ XML sang JSON. Sử dụng nhóm <Options> để thêm các chế độ cài đặt lượt chuyển đổi cụ thể hoặc phần tử <Format> để tham chiếu đến một mẫu gồm các lựa chọn được xác định trước. Bạn không thể sử dụng cả <Options> và <Format>.

Bạn phải sử dụng <Options> nếu không dùng <Format>.

Phần tử <Options>/<RecognizeNumber>

Nếu đúng, các trường số trong tải trọng XML sẽ giữ lại định dạng ban đầu.

<RecognizeNumber>true</RecognizeNumber>

Hãy xem xét ví dụ sau đây về XML:

<a>
  <b>100</b>
  <c>value</c>
</a>

Nếu true, chuyển đổi thành:

{
    "a": {
        "b": 100,
        "c": "value"
    }
}

Nếu false, chuyển đổi thành:

{
    "a": {
        "b": "100",
        "c": "value"
    }
}

Phần tử <Options>/<RecognizeBoolean>

Cho phép lượt chuyển đổi duy trì các giá trị boolean true/false thay vì chuyển các giá trị thành chuỗi.

<RecognizeBoolean>true</RecognizeBoolean>

Đối với ví dụ XML sau:

<a>
  <b>true</b>
  <c>value</c>
</a>

Nếu true, chuyển đổi thành:

{
    "a": {
        "b": true,
        "c": "value"
    }
}

Nếu false, chuyển đổi thành:

{
    "a": {
        "b": "true",
        "c": "value"
    }
}

Phần tử <Options>/<RecognizeNull>

Cho phép bạn chuyển đổi giá trị trống thành giá trị rỗng.

<RecognizeNull>true</RecognizeNull>

Đối với XML sau:

<a>
  <b></b>
  <c>value</c>
</a>

Nếu true, chuyển đổi thành:

{
  "a": {
    "b": null,
    "c": "value"
  }
}

Nếu false, chuyển đổi thành:

{
  "a": {
    "b": {},
    "c": "value"
  }
}

Phần tử <Options>/<NullValue>

Cho biết giá trị mà các giá trị rỗng được nhận dạng trong thông báo nguồn sẽ được chuyển đổi. Theo mặc định, giá trị này là null. Tuỳ chọn này chỉ có hiệu lực nếu RecognizeNull là true.

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator>

Kết hợp các phần tử này.

<NamespaceBlockName>#namespaces</NamespaceBlockName>
<DefaultNamespaceNodeName>&</DefaultNamespaceNodeName>
<NamespaceSeparator>***</NamespaceSeparator>

Hãy xem xét ví dụ sau đây về XML:

<a xmlns="http://ns.com" xmlns:ns1="http://ns1.com">
  <ns1:b>value</ns1:b>
</a>

Nếu bạn không chỉ định NamespaceSeparator, cấu trúc JSON sau đây sẽ được tạo:

{
    "a": {
        "b": "value"
    }
}

Nếu các phần tử NamespaceBlockName, DefaultNamespaceNodeName và NamespaceSeparator được chỉ định lần lượt là #namespaces, & và ***, thì cấu trúc JSON sau đây sẽ được tạo:

{
    "a": {
        "#namespaces": {
            "&": "http://ns.com",
            "ns1": "http://ns1.com"
        },
        "ns1***b": "value"
    }
}

<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName>

Kết hợp các phần tử này.

Nếu được đặt thành true, nội dung của phần tử XML sẽ được chuyển đổi thành một thuộc tính chuỗi.

<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<TextNodeName>TEXT</TextNodeName>

Đối với XML sau:

<a>
  <b>value1</b>
  <c>value2<d>value3</d>value4</c>
</a>

Nếu TextAlwaysAsProperty được đặt thành true và TextNodeName được chỉ định là TEXT, thì cấu trúc JSON sau sẽ được tạo:

{
  "a": {
    "b": {
      "TEXT": "value1"
    },
    "c": {
      "TEXT": [
        "value2",
        "value4"
        ],
        "d": {
          "TEXT": "value3"
        }
      }
    }
}

Nếu TextAlwaysAsProperty được đặt thành false và TextNodeName được chỉ định là TEXT, thì cấu trúc JSON sau sẽ được tạo:

{
  "a": {
    "b": "value1",
    "c": {
      "TEXT": [
        "value2",
        "value4"
      ],
      {
        "d": "value3",
      }
    }
}

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix>

Kết hợp các phần tử này.

Cho phép bạn nhóm các giá trị thành một khối JSON và thêm tiền tố vào tên thuộc tính.

<AttributeBlockName>FOO_BLOCK</AttributeBlockName>
<AttributePrefix>BAR_</AttributePrefix>

Hãy xem xét ví dụ sau đây về XML:

<a attrib1="value1" attrib2="value2"/>

Nếu cả hai thuộc tính (AttributeBlockName và AttributePrefix) đều được chỉ định như được xác định trong ví dụ về XML sang JSON, thì cấu trúc JSON sau đây sẽ được tạo:

{
  "a": {
    "FOO_BLOCK": {
      "BAR_attrib1": "value1",
      "BAR_attrib2": "value2"
    }
  }
}

Nếu chỉ định AttributeBlockName, cấu trúc JSON sau đây sẽ được tạo:

{
    "a": {
        "FOO_BLOCK": {
            "attrib1": "value1",
            "attrib2": "value2"
        }
    }
}

Nếu chỉ định AttributePrefix, cấu trúc JSON sau đây sẽ được tạo:

{
    "a": {
        "BAR_attrib1": "value1",
        "BAR_attrib2": "value2"
    }
}

Nếu không có thông số nào được chỉ định, cấu trúc JSON sau đây sẽ được tạo:

{
    "a": {
        "attrib1": "value1",
        "attrib2": "value2"
    }
}

Các phần tử <Options>/<OutputPrefix>
<Options>/<OutputSuffix>

Kết hợp các phần tử này.

<OutputPrefix>PREFIX_</OutputPrefix>
<OutputSuffix>_SUFFIX</OutputSuffix>

Hãy xem xét ví dụ sau đây về XML:

<a>value</a>

Nếu cả hai thuộc tính (OutputPrefix và OutputSuffix) đều được chỉ định như được xác định trong ví dụ về XML sang JSON, thì cấu trúc JSON sau đây sẽ được tạo:

PREFIX_{
    "a": "value"
}_SUFFIX

Nếu chỉ có OutputPrefix được chỉ định, thì cấu trúc JSON sau đây sẽ được tạo:

PREFIX_{
  "a" : "value"
}

Nếu chỉ có OutputSuffix được chỉ định, thì cấu trúc JSON sau đây sẽ được tạo:

{
  "a" : "value"
}_SUFFIX

Nếu bạn không chỉ định OutputPrefix và OutputSuffix, thì cấu trúc JSON sau đây sẽ được tạo:

{
    "a": "value"
}

Phần tử <Options>/<StripLevels>

<Options>
    <StripLevels>4</StripLevels>
</Options>

Đôi khi, các tải trọng XML (chẳng hạn như SOAP) có nhiều cấp độ mẹ mà bạn không muốn đưa vào JSON đã chuyển đổi. Sau đây là ví dụ về phản hồi SOAP chứa nhiều cấp:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/Schemata-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <GetCityWeatherByZIPResponse xmlns="http://ws.cdyne.com/WeatherWS/">
          <GetCityWeatherByZIPResult>
              <State>CO</State>
              <City>Denver</City>
              <Description>Sunny</Description>
              <Temperature>62</Temperature>
          </GetCityWeatherByZIPResult>
      </GetCityWeatherByZIPResponse>
  </soap:Body>
</soap:Envelope>

Có 4 cấp trước khi bạn đạt đến cấp Tiểu bang, Thành phố, Nội dung mô tả và Nhiệt độ. Nếu không dùng <StripLevels>, phản hồi JSON đã chuyển đổi sẽ có dạng như sau:

{
   "Envelope" : {
      "Body" : {
         "GetCityWeatherByZIPResponse" : {
            "GetCityWeatherByZIPResult" : {
               "State" : "CO",
               "City" : "Denver",
               "Description" : "Sunny",
               "Temperature" : "62"
            }
         }
      }
   }
}

Nếu muốn xoá 4 cấp đầu tiên trong phản hồi JSON, bạn sẽ đặt <StripLevels>4</StripLevels>. Thao tác này sẽ cung cấp cho bạn JSON sau đây:

{
  "State" : "CO",
  "City" : "Denver",
  "Description" : "Sunny",
  "Temperature" : "62"
}

Bạn có thể loại bỏ các cấp độ cho đến phần tử đầu tiên chứa nhiều phần tử con. Điều đó có nghĩa là gì? Hãy xem một ví dụ phức tạp hơn về JSON:

{
   "Envelope" : {
      "Body" : {
         "GetCityForecastByZIPResponse" : {
            "GetCityForecastByZIPResult" : {
               "ResponseText" : "City Found",
               "ForecastResult" : {
                  "Forecast" : [
                     {
                        "ProbabilityOfPrecipiation" : {
                           "Nighttime" : "00",
                           "Daytime" : 10
                        }  ...

Cấp 3 trong ví dụ này là GetCityForecastByZIPResponse, chỉ có một phần tử con. Vì vậy, nếu bạn sử dụng <StripLevels>3</StripLevels> (xoá 3 cấp đầu tiên), thì JSON sẽ có dạng như sau:

{
   "GetCityForecastByZIPResult" : {
      "ResponseText" : "City Found",
      "ForecastResult" : {
         "Forecast" : [
            {
               "ProbabilityOfPrecipiation" : {
                  "Nighttime" : "00",
                  "Daytime" : 10
               }  ...

Lưu ý rằng GetCityForecastByZIPResult có nhiều thành phần con. Vì đây là phần tử đầu tiên chứa nhiều phần tử con, nên bạn có thể loại bỏ cấp cuối cùng này bằng cách sử dụng <StripLevels>4</StripLevels>. Thao tác này sẽ cung cấp cho bạn JSON sau:

{
   "ResponseText" : "City Found",
   "ForecastResult" : {
      "Forecast" : [
         {
            "ProbabilityOfPrecipiation" : {
               "Nighttime" : "00",
               "Daytime" : 10
            }  ...

Vì cấp 4 là cấp đầu tiên chứa nhiều thành phần con, nên bạn không thể xoá bất kỳ cấp nào thấp hơn cấp này. Nếu đặt cấp độ dải thành 5, 6, 7, v.v., bạn sẽ tiếp tục nhận được phản hồi như trên.

Phần tử <Options>/<TreatAsArray>/<Path>

<Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

Sự kết hợp giữa các phần tử này giúp bạn đảm bảo rằng các giá trị trong tài liệu XML được đặt trong một mảng JSON. Ví dụ: điều này rất hữu ích khi số lượng phần tử con có thể thay đổi (từ một đến nhiều) và bạn muốn đảm bảo các giá trị luôn nằm trong một mảng. Việc này giúp giữ cho mã của bạn ổn định, vì bạn có thể lấy dữ liệu từ mảng theo cùng một cách mỗi lần. Ví dụ: $.teachers.teacher.studentnames[0] sẽ nhận giá trị tên của học viên đầu tiên trong mảng, bất kể số lượng giá trị trong mảng.

Hãy quay lại và xem hành vi mặc định của XML sang JSON, sau đó khám phá cách kiểm soát đầu ra bằng cách sử dụng <TreatAsArray>/<Path>.

Khi một tài liệu XML chứa một phần tử có nhiều giá trị con (thường dựa trên một lược đồ mà maxOccurs='unbounded' của phần tử đó), chính sách XML sang JSON sẽ tự động đặt các giá trị đó vào một mảng. Ví dụ: khối XML sau

<teacher>
    <name>teacherA</name>
    <studentnames>
        <name>student1</name>
        <name>student2</name>
    </studentnames>
</teacher>

...sẽ tự động chuyển đổi thành JSON sau đây mà không cần cấu hình chính sách đặc biệt:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}
           }
      }
}

Lưu ý rằng hai tên học viên được đưa vào một mảng.

Tuy nhiên, nếu chỉ có một học viên xuất hiện trong tài liệu XML, thì chính sách XML sang JSON sẽ tự động coi giá trị đó là một chuỗi duy nhất, chứ không phải là một mảng chuỗi, như minh hoạ trong ví dụ sau:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : "student1"
              }
          }
      }
}

Trong các ví dụ trước, dữ liệu tương tự được chuyển đổi theo cách khác nhau, một lần dưới dạng mảng, một lần dưới dạng một chuỗi duy nhất. Đây là nơi phần tử <TreatAsArray>/<Path> cho phép bạn kiểm soát đầu ra. Ví dụ: bạn có thể đảm bảo rằng tên của học viên luôn được đặt trong một mảng ngay cả khi chỉ có một giá trị. Bạn định cấu hình việc này bằng cách xác định Đường dẫn đến phần tử mà bạn muốn đặt giá trị vào một mảng, như sau:

<Options>
    <TreatAsArray>
        <Path>teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

Cấu hình ở trên sẽ ghi JSON như sau:

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : ["student1"]
              }
            ]
          }
      }
}

Xin lưu ý rằng student1 hiện nằm trong một mảng. Giờ đây, bất kể có một hay nhiều học viên, bạn đều có thể truy xuất họ từ một mảng JSON trong mã của mình bằng cách sử dụng JSONPath sau: $.teachers.teacher.studentnames.name[0]

Phần tử <Path> cũng có một thuộc tính unwrap, được giải thích trong phần tiếp theo.

Thuộc tính

 <Options>
    <TreatAsArray>
        <Path unwrap="true">teachers/teacher/studentnames/name</Path>
    </TreatAsArray>
</Options>

{
  "teachers" : {
      "teacher" : {
          "name" : "teacherA",
          "studentnames" : {
              "name" : [
                 "student1",
                 "student2"
              ]}...

<TreatAsArray>
    <Path unwrap="true">teachers/teacher</Path>
    <Path unwrap="true">teachers/teacher/studentnames/name</Path>
</TreatAsArray>

{
  "teachers" : [{
      "name" : "teacherA",
      "studentnames" : ["student1","student2"]
      }]...

Để xem thêm ví dụ và hướng dẫn về tính năng này, hãy xem bài viết này trên Cộng đồng Apigee: Hướng dẫn cho cộng đồng: Lựa chọn TreatAsArray trong chính sách XML sang JSON.

<Format>

Định dạng cho phép bạn kiểm soát quá trình chuyển đổi từ XML sang JSON. Nhập tên của một mẫu được xác định trước có chứa một tổ hợp cụ thể gồm các phần tử Lựa chọn được mô tả trong chủ đề này. Các định dạng được xác định trước bao gồm: xml.com, yahoo, google, badgerFish.

Dùng phần tử <Format> hoặc nhóm <Options>. Bạn không thể sử dụng cả <Format> và <Options>.

Sau đây là định nghĩa về Định dạng của từng mẫu được xác định trước.

xml.com

<RecognizeNull>true</RecognizeNull>
<TextNodeName>#text</TextNodeName>
<AttributePrefix>@</AttributePrefix>

yahoo

<RecognizeNumber>true</RecognizeNumber>
<TextNodeName>content</TextNodeName>

google

<TextNodeName>$t</TextNodeName>
<NamespaceSeparator>$</NamespaceSeparator>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>

badgerFish

<TextNodeName>$</TextNodeName>
<TextAlwaysAsProperty>true</TextAlwaysAsProperty>
<AttributePrefix>@</AttributePrefix>
<NamespaceSeparator>:</NamespaceSeparator>
<NamespaceBlockName>@xmlns</NamespaceBlockName>
<DefaultNamespaceNodeName>$</DefaultNamespaceNodeName>

Cú pháp phần tử:

<Format>yahoo</Format>

Giản đồ

Tham chiếu lỗi

Phần này mô tả các mã lỗi và thông báo lỗi được trả về cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này rất quan trọng nếu bạn đang phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi chính sách này thực thi.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy có chứa chính sách này.

Biến lỗi

Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi khi gặp lỗi

{
  "fault": {
    "faultstring": "XMLToJSON[XMLtoJSON-1]: Source xyz is not available",
    "detail": {
      "errorcode": "steps.xml2json.SourceUnavailable"
    }
  }
}

Ví dụ về quy tắc lỗi

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="XML to JSON Faults">
    <Step>
        <Name>AM-SourceUnavailableMessage</Name>
        <Condition>(fault.name Matches "SourceUnavailable") </Condition>
    </Step>
    <Step>
        <Name>AM-BadXML</Name>
        <Condition>(fault.name = "ExecutionFailed")</Condition>
    </Step>
    <Condition>(xmltojson.XMLtoJSON-1.failed = true) </Condition>
</FaultRule>

Chủ đề có liên quan

JSON sang XML: Chính sách JSON sang XML