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 JavaScript Object Notation (JSON) sang ngôn ngữ đánh dấu có thể mở rộng (XML), 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.
Chính sách này đặc biệt hữu ích nếu bạn muốn chuyển đổi thư bằng NDK. Sau khi chuyển đổi tải trọng JSON thành XML, hãy sử dụng chính sách Chuyển đổi NDK với biểu định kiểu tuỳ chỉnh để thực hiện việc chuyển đổi mà bạn cần.
Giả sử ý định là chuyển đổi yêu cầu có định dạng JSON thành yêu cầu có định dạng XML, thì chính sách này sẽ được đính kèm vào Luồng yêu cầu (ví dụ: Request / ProxyEndpoint/PostFlow).
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.
Chuyển đổi một yêu cầu
<JSONToXML name="jsontoxml"> <Source>request</Source> <OutputVariable>request</OutputVariable> </JSONToXML>
Cấu hình này sẽ lấy thông báo yêu cầu có định dạng JSON làm nguồn, sau đó tạo một thông báo có định dạng XML được điền vào request
OutputVariable. Edge tự động sử dụng nội dung của biến này làm thông báo cho bước xử lý tiếp theo.
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.
<JSONToXML async="false" continueOnError="false" enabled="true" name="JSON-to-XML-1"> <DisplayName>JSON to XML 1</DisplayName> <Source>request</Source> <OutputVariable>request</OutputVariable> <Options> <OmitXmlDeclaration>false</OmitXmlDeclaration> <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName> <NamespaceSeparator>:</NamespaceSeparator> <AttributeBlockName>#attrs</AttributeBlockName> <AttributePrefix>@</AttributePrefix> <ObjectRootElementName>Root</ObjectRootElementName> <ArrayRootElementName>Array</ArrayRootElementName> <ArrayItemElementName>Item</ArrayItemElementName> <Indent>false</Indent> <TextNodeName>#text</TextNodeName> <NullValue>I_AM_NULL</NullValue> <InvalidCharsReplacement>_</InvalidCharsReplacement> </Options> </JSONToXML>
Thuộc tính <JSONToXML>
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:
Thuộc tính | Nội dung mô tả | Mặc định | Sự hiện diện |
---|---|---|---|
name |
Tên nội bộ của chính sách. Giá trị của thuộc tính Nếu muốn, bạn có thể sử dụng phần tử |
Không áp dụng | Bắt buộc |
continueOnError |
Đặt thành Đặt thành |
false | Không bắt buộc |
enabled |
Đặt thành Đặt thành |
đúng | Không bắt buộc |
async |
Thuộc tính này không được dùng nữa. |
false | Không được dùng nữa |
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>
Mặc định |
Không áp dụng Nếu bạn bỏ qua phần tử này, thì giá trị thuộc tính |
---|---|
Sự hiện diện | Không bắt buộc |
Loại | Chuỗi |
Phần tử <Source>
Biến, yêu cầu hoặc phản hồi chứa thông báo JSON mà bạn muốn chuyển đổi sang XML.
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>request</Source>
Mặc định | yêu cầu hoặc phản hồi, được xác định theo nơi thêm chính sách vào quy trình proxy API |
Sự hiện diện | Không bắt buộc |
Loại | tin nhắn |
Phần tử <OutputVariable>
Lưu trữ dữ liệu đầu ra của lượt chuyển đổi định dạng JSON sang XML. Giá trị này thường có cùng giá trị với nguồn, tức là thường thì yêu cầu JSON sẽ được chuyển đổi thành yêu cầu XML.
Tải trọng của thông báo JSON được phân tích cú pháp và chuyển đổi thành XML, 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 text/xml;charset=UTF-8
.
Nếu bạn không chỉ định OutputVariable
, source
sẽ được coi là OutputVariable
. Ví dụ: nếu source
là request
, thì OutputVariable
sẽ mặc định là request
.
<OutputVariable>request</OutputVariable>
Mặc định | yêu cầu hoặc phản hồi, được xác định theo nơi thêm chính sách vào quy trình proxy API |
Sự hiện diện | Phần tử này là bắt buộc khi biến được xác định trong phần tử <Source> thuộc kiểu chuỗi. |
Loại | tin nhắn |
<Tuỳ chọn>/<OmitXmlDeclaration>
Chỉ định bỏ qua không gian tên XML khỏi kết quả. Giá trị mặc định là false
, nghĩa là bao gồm không gian tên trong dữ liệu đầu ra.
Ví dụ: chế độ cài đặt sau đây định cấu hình chính sách để bỏ qua không gian tên:
<OmitXmlDeclaration>true</OmitXmlDeclaration>
<Options>/<NamespaceBlockName>
<Options>/<DefaultNamespaceNodeName>
Phần tử <Options>/<Namespaceseparator>
JSON không hỗ trợ không gian tên, trong khi các tài liệu XML thường yêu cầu không gian tên.
NamespaceBlockName
cho phép bạn xác định một thuộc tính JSON đóng vai trò là nguồn của định nghĩa không gian tên trong tệp XML do chính sách này tạo ra. (Điều này có nghĩa là JSON nguồn phải cung cấp một thuộc tính có thể liên kết thành một không gian tên mà ứng dụng sử dụng XML kết quả dự kiến.)
Ví dụ: các chế độ cài đặt sau đây:
<NamespaceBlockName>#namespaces</NamespaceBlockName> <DefaultNamespaceNodeName>$default</DefaultNamespaceNodeName> <NamespaceSeparator>:</NamespaceSeparator>
cho biết rằng một thuộc tính có tên là #namespaces
tồn tại trong JSON nguồn chứa ít nhất một không gian tên được chỉ định làm mặc định. Ví dụ:
{ "population": { "#namespaces": { "$default": "http://www.w3.org/1999/people", "exp": "http://www.w3.org/1999/explorers" }, "person": "John Smith", "exp:person": "Pedro Cabral" } }
chuyển đổi thành:
<population xmlns="http://www.w3.org/1999/people" xmlns:exp="http://www.w3.org/1999/explorers"> <person>John Smith</person> <exp:person>Pedro Cabral</exp:person> </population>
<Options>/<ObjectRootElementName>
<ObjectRootElementName> chỉ định tên phần tử gốc khi bạn chuyển đổi từ JSON (không có phần tử gốc đã đặt tên) sang XML.
Ví dụ: nếu JSON xuất hiện dưới dạng:
{ "abc": "123", "efg": "234" }
Và bạn đặt <ObjectRootElementName> là:
<ObjectRootElementName>Root</ObjectRootElementName>
XML tổng hợp sẽ có dạng như sau:
<Root> <abc>123</abc> <efg>234</efg> </Root>
<Options>/<AttributeBlockName>
Phần tử <Options>/<AttributePrefix>
<AttributeBlockName>
cho phép bạn chỉ định thời điểm các phần tử JSON được chuyển đổi thành các thuộc tính XML (thay vì phần tử XML).
Ví dụ: chế độ cài đặt sau đây sẽ chuyển đổi các thuộc tính bên trong một đối tượng có tên #attrs
thành các thuộc tính XML:
<AttributeBlockName>#attrs</AttributeBlockName>
Đối tượng JSON sau:
{ "person" : { "#attrs" : { "firstName" : "John", "lastName" : "Smith" }, "occupation" : "explorer", } }
được chuyển đổi sang cấu trúc XML sau:
<person firstName="John" lastName="Smith"> <occupation>explorer</occupation> </person>
<AttributePrefix>
chuyển đổi thuộc tính bắt đầu bằng tiền tố đã chỉ định thành các thuộc tính XML. Trong trường hợp tiền tố thuộc tính được đặt thành @
, ví dụ:
<AttributePrefix>@</AttributePrefix>
Chuyển đổi đối tượng JSON sau:
{ "person" : { "@firstName" : "John", "@lastName" : "Smith" "occupation" : "explorer", } }
sang cấu trúc XML sau:
<person firstName="John" lastName="Smith"> <occupation>explorer</occupation> </person>
<Options>/<ArrayRootElementName>
Phần tử <Options>/<ArrayItemElementName>
Chuyển đổi một mảng JSON thành danh sách các phần tử XML có tên phần tử mẹ và phần tử con được chỉ định.
Ví dụ: các chế độ cài đặt sau đây:
<ArrayRootElementName>Array</ArrayRootElementName> <ArrayItemElementName>Item</ArrayItemElementName>
chuyển đổi mảng JSON sau:
[ "John Cabot", { "explorer": "Pedro Cabral" }, "John Smith" ]
vào cấu trúc XML sau:
<Array> <Item>John Cabot</Item> <Item> <explorer>Pedro Cabral</explorer> </Item> <Item>John Smith</Item> </Array>
<Tùy chọn>/<Giảm thụt lề>
Chỉ định thụt lề đầu ra XML. Giá trị mặc định là false
có nghĩa là không thụt lề.
Ví dụ: chế độ cài đặt sau đây định cấu hình chính sách cho phép thụt lề đầu ra:
<Indent>true</Indent>
Nếu tệp JSON nhập ở dạng:
{"n": [1, 2, 3] }
Khi đó, kết quả không thụt lề là:
<Array><n>1</n><n>2</n><n>3</n></Array>
Khi bật tính năng thụt lề, kết quả sẽ là:
<Array> <n>1</n> <n>2</n> <n>3</n> </Array>
Phần tử <Options>/<TextNodeName>
Chuyển đổi thuộc tính JSON thành nút văn bản XML có tên đã chỉ định. Ví dụ: chế độ cài đặt sau:
<TextNodeName>age</TextNodeName>
chuyển đổi JSON này:
{ "person": { "firstName": "John", "lastName": "Smith", "age": 25 } }
đối với cấu trúc XML này:
<person> <firstName>John</firstName>25<lastName>Smith</lastName> </person>
Nếu bạn không chỉ định TextNodeName
, XML sẽ được tạo bằng chế độ cài đặt mặc định cho nút văn bản:
<person> <firstName>John</firstName> <age>25</age> <lastName>Smith</lastName> </person>
Phần tử <Options>/<NullValue>
Cho biết có giá trị rỗng. Theo mặc định, giá trị là NULL
.
Ví dụ: chế độ cài đặt sau:
<NullValue>I_AM_NULL</NullValue>Chuyển đổi đối tượng JSON sau:
{"person" : "I_AM_NULL"}
thành phần tử XML sau:
<person></person>
Khi không có giá trị nào (hoặc một giá trị khác I_AM_NULL
) được chỉ định cho giá trị Null, thì tải trọng đó sẽ chuyển đổi thành:
<person>I_AM_NULL</person>
Phần tử <Options>/<InvalidCharsReplacement>
Để hỗ trợ xử lý XML không hợp lệ có thể gây ra sự cố với trình phân tích cú pháp, chế độ cài đặt này sẽ thay thế mọi phần tử JSON tạo ra XML không hợp lệ bằng chuỗi. Ví dụ: chế độ cài đặt sau đây:
<InvalidCharsReplacement>_</InvalidCharsReplacement>
Chuyển đổi đối tượng JSON này
{ "First%%%Name": "John" }
đối với cấu trúc XML này:
<First_Name>John<First_Name>
Lưu ý về cách sử dụng
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 XMLtoJSON trong quy trình 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ụ vốn chỉ hỗ trợ XML.
Thông thường, bạn nên áp dụng chính sách JSON mặc định (trống) cho XML và thêm các phần tử cấu hình lặp lại theo yêu cầu.
Đối với các trường hợp mà API được sử dụng bởi nhiều ứng dụng có thể yêu cầu JSON và XML, bạn có thể đặt định dạng phản hồi một cách 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.
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.
Mã lỗi | Trạng thái HTTP | Nguyên nhân | Khắc phục |
---|---|---|---|
steps.jsontoxml.ExecutionFailed |
500 | Tải trọng đầu vào (JSON) trống hoặc dữ liệu đầu vào (JSON) được chuyển qua JSON vào chính sách XML không hợp lệ hoặc không đúng định dạng. | build |
steps.jsontoxml.InCompatibleTypes |
500 | Lỗi này xảy ra nếu loại biến được xác định trong phần tử <Source> và phần tử <OutputVariable> không giống nhau. Loại bắt buộc của các biến có trong phần tử <Source> và phần tử <OutputVariable> phải khớp với nhau. Loại hợp lệ là message và string . |
build |
steps.jsontoxml.InvalidSourceType |
500 | Lỗi này xảy ra nếu loại biến dùng để xác định phần tử <Source> không hợp lệ. Các loại biến hợp lệ là message và string . |
build |
steps.jsontoxml.OutputVariableIsNotAvailable |
500 | Lỗi này xảy ra nếu biến được chỉ định trong phần tử <Source> của Chính sách JSON cho XML thuộc loại chuỗi và phần tử <OutputVariable> không được xác định.
Phần tử <OutputVariable> là bắt buộc khi biến được xác định trong phần tử <Source> thuộc kiểu chuỗi. |
build |
steps.jsontoxml.SourceUnavailable |
500 |
Lỗi này xảy ra nếu biến thông báo được chỉ định trong phần tử <Source> của chính sách JSON cho XML thuộc một trong hai trường hợp sau:
|
build |
Lỗi triển khai
Không nội dung nào.
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.
Biến | Trong đó | Ví dụ: |
---|---|---|
fault.name="fault_name" |
fault_name là tên của lỗi, như liệt kê trong bảng Lỗi thời gian chạy ở trên. Tên lỗi là phần cuối cùng của mã lỗi. | fault.name Matches "SourceUnavailable" |
jsontoxml.policy_name.failed |
policy_name là tên của chính sách báo lỗi do người dùng chỉ định. | jsontoxml.JSON-to-XML-1.failed = true |
Ví dụ về phản hồi lỗi
{ "fault": { "faultstring": "JSONToXML[JSON-to-XML-1]: Source xyz is not available", "detail": { "errorcode": "steps.json2xml.SourceUnavailable" } } }
Ví dụ về quy tắc lỗi
<FaultRule name="JSON To XML Faults"> <Step> <Name>AM-SourceUnavailableMessage</Name> <Condition>(fault.name Matches "SourceUnavailable") </Condition> </Step> <Step> <Name>AM-BadJSON</Name> <Condition>(fault.name = "ExecutionFailed")</Condition> </Step> <Condition>(jsontoxml.JSON-to-XML-1.failed = true) </Condition> </FaultRule>
Chủ đề có liên quan
- XML sang JSON: Chính sách XML sang JSON
- Chuyển đổi NDK: Chính sách chuyển đổi XSL