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 các thông báo từ định dạng ngôn ngữ đánh dấu có thể mở rộng (XML) thành JavaScript Object Notation (JSON), cung cấp cho bạn nhiều lựa chọn để kiểm soát cách chuyển đổi thông báo.

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

Giới thiệu

Trong một trường hợp dàn xếp thông thường, chính sách JSON sang XML trên quy trình yêu cầu gửi đến thường được kết hợp 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, API JSON có thể hiển thị cho các dịch vụ phụ trợ vốn chỉ hỗ trợ XML.

Đối với các trường hợp mà 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 đặt linh động bằng cách định cấu hình các chính sách 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 luồng để biết cách triển khai tình huống này.

Mẫu

Để thảo luận chi tiết về việc chuyển đổi giữa JSON và XML, hãy 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ử

Dưới đây là các phần tử và thuộc tính mà bạn có thể thiết lập trong 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ả các thuộc tính chung cho tất cả phần tử mẹ của chính sách:

Phần tử <DisplayName>

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

<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 đề Loại nội dung HTTP của thông báo nguồn 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ì <Source> đó sẽ được coi là thông báo (sẽ phân giải yêu cầu khi chính sách đượ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 phân giải được hoặc chuyển thành loại không phải nội dung, thì chính sách sẽ gửi lỗi.

<Source>response</Source>

Phần tử <OutputVariable>

Lưu trữ dữ liệu đầu ra của lượt chuyển đổi định dạng XML sang JSON. Giá trị này thường có cùng giá trị với nguồn, nghĩa 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, còn tiêu đề Loại nội dung HTTP 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 sẽ mặc định là response.

<OutputVariable>response</OutputVariable>

<Tuỳ chọn>

Các tuỳ chọn cho phép bạn kiểm soát việc 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> để cho phép bạn tham chiếu đến mẫu gồm các lựa chọn được xác định trước. Bạn không được sử dụng cả <Options> và <Format>.

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

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

Nếu đúng thì 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 ví dụ XML sau:

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

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

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

Nếu false, sẽ 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 đúng/sai 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, sẽ chuyển đổi thành:

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

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

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

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

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, sẽ chuyển đổi thành:

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

Nếu false, sẽ 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 thành. Theo mặc định, giá trị là null. Tuỳ chọn này chỉ có hiệu lực nếu RecognizeNull là giá trị true.

<NullValue>not-present</NullValue>

<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
Phần tử <Options>/<Namespaceseparator>

Hãy sử dụng kết hợp các thành phần này.

<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ẽ đượ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 sẽ được tạo:

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

Phần tử <Options>/<TextAlwaysAsProperty>
Các phần tử <Options>/<TextNodeName>

Hãy sử dụng kết hợp các thành phần này.

Nếu bạn đặt thành true, nội dung của phần tử XML sẽ được chuyển đổi thành 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 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, thì cấu trúc JSON sau sẽ được tạo:

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

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

Hãy sử dụng kết hợp các thành phần này.

Cho phép bạn nhóm các giá trị vào 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) được chỉ định như xác định trong ví dụ từ XML sang JSON, thì 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, thì cấu trúc JSON sau đây sẽ được tạo:

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

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

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

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

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

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

Hãy sử dụng kết hợp các thành phần này.

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

Hãy xem ví dụ XML sau:

<a>value</a>

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

PREFIX_{
    "a": "value"
}_SUFFIX

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

PREFIX_{
  "a" : "value"
}

Nếu bạn chỉ định OutputSuffix, cấu trúc JSON sau 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 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 độ gốc mà bạn không muốn đưa vào JSON đã chuyển đổi. Dưới đây là ví dụ về một phản hồi SOAP có 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 chuyển đến Tiểu bang, Thành phố, Mô tả và Nhiệt độ. Nếu không sử 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 loại bỏ 4 cấp độ đầu tiên đó trong phản hồi JSON, bạn nên đặt <StripLevels>4</StripLevels>. Thao tác này sẽ cho bạn JSON sau:

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

Bạn có thể tách các cấp độ khỏi phần tử đầu tiên chứa nhiều phần tử con. Điều này có nghĩa là gì? Hãy xem 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 thành phần con. Vì vậy, nếu bạn sử dụng <StripLevels>3</StripLevels> (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
               }  ...

Xin lưu ý rằng GetCityForecastByZIPResult có nhiều phần tử con. Vì đây là phần tử đầu tiên chứa nhiều phần tử con, nên bạn có thể tách cấp cuối cùng này bằ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 phần tử con, nên bạn không thể tách 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 ở trên.

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

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

Tổ hợp phần tử này cho phép bạn đảm bảo rằng các giá trị trong tài liệu XML sẽ được đưa vào một mảng JSON. Điều này rất hữu ích, chẳng hạn như 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. Cách này sẽ giúp mã của bạn luôn ổn định vì bạn luôn có thể lấy dữ liệu từ mảng theo cùng một cách. Ví dụ: $.teachers.teacher.studentnames[0] lấy giá trị tên học viên đầu tiên trong mảng, bất kể số lượng giá trị trong mảng.

Hãy lùi lại một bước và xem hành vi mặc định của XML sang JSON, rồi tìm hiểu cách kiểm soát dữ liệu đầu ra bằng <TreatAsArray>/<Path>.

Khi 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 đồ 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>

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

Lưu ý rằng birthday1 hiện đang 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 các học viê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. Điều này sẽ đượ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 từng bước về tính năng, hãy tham khảo 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.

<Định dạng>

Định dạng cho phép bạn kiểm soát việc chuyển đổi từ XML sang JSON. Nhập tên của một mẫu được xác định trước chứa tổ hợp cụ thể các phần tử Tuỳ 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.

Hãy sử dụng phần tử <Format> hoặc nhóm <Options>. Bạn không được sử dụng cả <Format> và <Options>.

Sau đây là các định nghĩa Đị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 đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem 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 thực thi chính sách.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai proxy 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 Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi 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