Chính sách XMLtoJSON

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến Tài liệu về 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 JavaScript Ký hiệu đối tượng (JSON), cung cấp cho bạn nhiều lựa chọn để kiểm soát cách thông báo được đã chuyển đổi.

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

Giới thiệu

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

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

Mẫu

Để thảo luận chi tiết về cách chuyển đổi giữa JSON và XML, vui lòng xem http://community.apigee.com/articles/1839/converting-between-xml-and-json-what-you-need-to-k.html.

<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ể thiết lập theo 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>

<XMLtoJSON> thuộc tính

<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:

<DisplayName> 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>

<Source> phần tử

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.

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

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

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

<Source>response</Source>

<OutputVariable> phần tử

Lưu trữ kết quả của quá trình chuyển đổi định dạng XML sang JSON. Giá trị này thường giống với 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, và loại nội dung HTTP phần đầu thư của thông báo theo định dạng XML được đặt thành application/json.

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

<OutputVariable>response</OutputVariable>

<Options>

Các tuỳ chọn cho phép bạn kiểm soát quá trình chuyển đổi từ XML sang JSON. Sử dụng <Options>, cho phép bạn thêm các chế độ cài đặt lượt chuyển đổi cụ thể hoặc <Format> cho phép bạn tham chiếu mẫu của các tuỳ chọn định sẵn. Bạn không thể sử dụng cả <Options> và <Format>.

Bạn phải nhập <Options> nếu không dùng <Format>.

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

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

<RecognizeNumber>true</RecognizeNumber>

Hãy xem ví dụ XML sau:

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

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

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

<RecognizeBoolean>true</RecognizeBoolean>

Trong 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"
    }
}

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

Cho phép bạn chuyển đổi các 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"
  }
}

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

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

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
<Options>/<NamespaceSeparator> phần tử

Sử dụng các phần tử này cùng nhau.

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

Hãy xem ví dụ XML sau:

<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 sẽ là đã tạo:

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

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

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

<Options>/<TextAlwaysAsProperty>
<Options>/<TextNodeName> phần tử

Sử dụng các phần tử này cùng nhau.

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

<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 bạn đặt TextAlwaysAsProperty 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 bạn đặt TextAlwaysAsProperty thành false và TextNodeName được chỉ định là TEXT, cấu trúc JSON sau đây là đã tạo:

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

<Options>/<AttributeBlockName>
<Options>/<AttributePrefix> phần tử

Sử dụng các phần tử này cùng nhau.

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 ví dụ XML sau:

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

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

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

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

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

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

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

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

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

<Options>/<OutputPrefix>
<Options>/<OutputSuffix> phần tử

Sử dụng các phần tử này cùng nhau.

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

Hãy xem ví dụ XML sau:

<a>value</a>

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

PREFIX_{
    "a": "value"
}_SUFFIX

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

PREFIX_{
  "a" : "value"
}

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

{
  "a" : "value"
}_SUFFIX

Nếu cả OutputPrefix và OutputSuffix đều không được chỉ định, thì hàm sau Cấu trúc JSON được tạo:

{
    "a": "value"
}

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

<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 được chuyển đổi. Dưới đâ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 chuyển đến cấp Tiểu bang, Thành phố, Nội dung mô tả và Nhiệt độ. Nếu không sử dụng <StripLevels>, phản hồi JSON được chuyển đổi sẽ trông giố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 nên đặt <StripLevels>4</StripLevels>, sẽ cung cấp cho bạn: JSON:

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

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

{
   "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 con. Vì vậy, nếu bạn định sử dụng <StripLevels>3</StripLevels> (hãy xoá 3 cấp độ đầu tiên), JSON sẽ có dạng như sau:

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

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

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

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

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

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

Tổ hợp 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 đưa vào định dạng JSON . Điều này hữu ích, ví dụ như khi số lượng phần tử con có thể thay đổi (từ 1 đến nhiều) và bạn muốn đảm bảo các giá trị luôn nằm trong một mảng. Cách này giúp đảm bảo mã ổn định vì bạn có thể lấy dữ liệu qua mảng theo cách giống nhau mọi lúc. Cho ví dụ: $.teachers.teacher.studentnames[0] nhận giá trị tên đầu tiên của học viên trong mảng bất kể số lượng giá trị trong mảng.

Hãy nhìn lại hành vi mặc định của XML sang JSON, sau đó tìm hiểu cách kiểm soát đầu ra bằ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 giản đồ trong đó maxOccurs='unbounded' của phần tử), thì 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>

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

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

Lưu ý rằng 2 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 từ XML sang JSON sẽ tự động coi giá trị là một chuỗi đơn, không phải là một mảng chuỗi, như minh hoạ sau ví dụ:

{
  "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 khác là một chuỗi đơn. Đây là nơi phần tử <TreatAsArray>/<Path> cho phép bạn kiểm soát đầu ra. Chẳng hạn, bạn có thể đảm bảo luôn nhập tên của các học viên một mảng ngay cả khi chỉ có một giá trị. Bạn định cấu hình điều này bằng cách xác định Đường dẫn đến phần tử có các giá trị bạn muốn đặt 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ẽ viết JSON như sau:

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

Xin lưu ý rằngstudent1 hiện đã nằm trong một mảng. Bây giờ, bất kể có một hay nhiều sinh viên, bạn có thể truy xuất các sự kiện đó 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ó thuộc tính unwrap, được giải thích bằng 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 từng bước về tính năng, hãy xem bài viết này trên Cộng đồng Apigee: https://community.apigee.com/content/kbentry/33374/new-edge-minifeature-the-treatasarray-option-in-th.html.

<Format>

Định dạng giúp bạn kiểm soát quá trình chuyển đổi từ XML sang JSON. Nhập tên của trạng thái được xác định trước mẫu chứa một tổ hợp cụ thể 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.

Sử 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à các đị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: JSON sang XML chính sách của Google