Returns a descendant value within a given JSON Entity.
A descendant's value if it was found, "" if not.
|Handle||Handle to a JSON Entity. Required.|
|Path||A formatted string indicating the desired descendant. Required.|
|Default||An alternative value to return if the descendant's value is null. Optional. If this argument is ommitted, then a null value will return "<null>".|
The GetValue service returns the value of a descendant entity somewhere within the current JSON Entity Handle. If the descendant is an object or array, then you'll get the entire JSON string for that entity. Otherwise, you'll get the element's value without extraneous formatting (like quotes around strings).
The term descendant is intentional because you can extract members or elements deep within the JSON tree in a single call. Let's use the following JSON as an example:
In this example, we have a root object with a single child object called "menu" as it's only member. That object contains a member called items, which is an array, and each element in the array is either null or a child object. As you can see, it would be cumbersome to extract a single descendant as it would require getting a child handle, followed by another child handle, and so on. That is why the GET service supports a path.
The path is a specially formatted string that instructs the service how to drill down into the JSON. If you pass a single member name or index, then you'll get the JSON string for that object. For example, we can get the "menu" object like so:
If you want to get a child of menu, you separate each member name with a period, like so:
If you want to get an element within an array, you use square brackets instead of periods. This is how we drill down directly to the twelfth element within the items array:
And this is how we get the handle to the "label" member of the second item in the items array:
Important. The Path parameter is a convenient way to drill into a JSON document. It reserves five characters: period, left square bracket, right square bracket, left angle bracket, and right angle bracket. If the member you want to access uses one of these characters, you must escape them by doubling up. Here's an example of a JSON document with periods in the member names and how to access them.