Schema、Resource、Operation

　　前面几节我们介绍了SOE基本概念、REST SOE模板以及如何处理输入输出数据。今天详细介绍一下SOE中三个重要概念：Schema、Resource、Operation。

1.Schema

　　SOE中的Resource和Operation所组成的结构就是Schema，也可以说Shcema确定了SOE中Resource和Operation的层次结构。通常由IRESTRequestHandler接口的GetSchema（）方法来返回该SOE的Schema，作为一个JSON格式的字符串被返回。在REST API中可以通过讲一个http请求的参数设置为“f=schema”来获取Schema。

　　下面我们来看几个Schema的例子

　　　　Schema1 只有一个Operation

{  "operations" : [ "buffer", "near" ]}　　在该例子中，SOE之暴露了一个Operation，从REST API角度来讲，这个SOE之暴露了两个URL。SOE跟资源和Buffer Operation：

http://<service-url>/exts/<extensionName> //root SOE resourcehttp://<service-url>/exts/<extensionName>/buffer //buffer operation

　　　　Schema2 有多个Operation

{  "operations" : [ "buffer", "near" ]}

　　在该Schema中Operation是一个数组，所以可以指定多个操作。从REST API角度来讲，这个SOE暴露了三个URL、SOE跟资源、Buffer和near操做：

http://<service-url>/exts/<extensionName> //root SOE resourcehttp://<service-url>/exts/<extensionName>/buffer //buffer operationhttp://<service-url>/exts/<extensionName>/near //near operation

　　　　Schema3 具有参数的Operation和它指定的参数以及输出格式

{  "operations" : [    {      "name" : "buffer",       "parameters" : ["location", "distance"],       "supportedOutputFormats" : ["json", "amf"]    },    {      "name" : "near",       "parameters" : ["location", "distance", "lookingFor"],       "supportedOutputFormats" : ["json"]    }  ]}它同Schema2暴露的URL是一样的，区别在于它不仅制定了Operation的名称，还有一些Operation的附属信息，稍后我们会继续讨论这种Schema。　　Schema 4  子Resource{  "name" : "MyMapServiceExtension",  "operations" : ["export", "identify"],  "resources" : [    {      "name" : "metadata"    },    {      "name" : "layers",      "isCollection" : true,      "operations" : ["query"],      "resources" : [        {          "name" : "features",          "isCollection" : true        }      ]    }  ]}　　该Schema中除了Operation外，还指定了它的子Resource。该SOE包含两个根级Operation：export和identify，同时也包含了两个子资源： metadata和layers。metadata资源可以通过以下URL获得：

http://<service-url>/exts/<extensionName>/metadata

　　注意到layers是一个Collection Resource（集合资源，因为其isCollection属性为true），可以通过以下URL访问它的子图层资源：

http://<service-url>/exts/<extensionName>/layers/<layerId>

　　同时，每一个图层都支持query操作，如下URL：

http://<service-url>/exts/<extensionName>/layers/<layerId>/query

　　每一个图层中又包含了features子资源。features也是一个集合资源，每个特定的feature可以通过以下URL访问：

http://<service-url>/exts/<extensionName>/layers/<layerId>/features/<featureId>

 

2.Resource

　　所有的SOE服务最少支持一个根级的Resource和Operation，如果Schema指定的话也可以包含子资源。

　　REST handler经常会从SOE中获取一个resource的json表达。如果客户端使用“f=json”开请求一个resource，SOE将会以json格式发送到客户端。另一方面，如果使用Services Directory显示的话，通常会将json转换为html形式显示在网页上。

　　现在假定通过SOE返回的json格式的根资源如下：

{  "description: "Contitental US",  "extent" : { "xmin" : ..., "ymin" : ..., ...},  "spatialReference" : {...},  ...    "layers" : [    { "id" : 0, "name" : "Cities", ... },    { "id" : 1, "name" : "Counties", ... },    { "id" : 2, "name" : "States", ... }  ]    ...}

　　当其在Services Directory中显示时，Rest handler会发现一个“layers”属性，由于他在Schema中被指定作为Collection Resource，将会首先检查这个属性（layers）的值是否是一个json数组，进一步检查每个元素是否是一个具有id和name属性的json对象。这样将会用他的name作为显示而将id放在放在URL连接中。点击Cities时会获得如下URL：

http://<service-url>/exts/<extensionName>/layers/0 //the Cities layer

在Services Directory中如下显示：

　　使用REST API获取一个SOE的resource，实际上是触发了SOE中的handleRESTRequest方法。对于resource请求，该方法的OpeartionName参数将是一个空字符串，而resourceName参数是一个跟SOE的resource相关的字符串。下图展示了在Schema4中对于不同的resource的REST请求，将被转换成handleRequest触发时的resourceName参数：

3.Operation

　　如果SOE的Schema中指定了某些resource支持Operation，该resource的Services Directory页面将会显示出Operation的链接。如：

 

　　在Schema2中之定义了一个Operation的名字，并没有参数和返回格式信息，这时Services Directory通常会显示一个form，用户需要在此提供参数信息和值，在Schema中的buffer Operation将会如下显示：

　　类似resource，用REST API发送Operation请求时也触发了HandleRESTRequest方法。这时候operationName将是一个非空字符串，resourceName将是一个与SOE的resource有关联的字符串。在Schema4中，发送不同的Operation请求，将被转换成handleRESTRequest触发时的resourceName和operationName：

　　REST客户端会把operation参数作为query parameter放在URL中。在handleRESTRequest出发之前，REST handle将输入参数强制转换成json对象，参数名作为json对象的属性名，参数值作为有意义的json对象值，如数字、bool、json对象、json数组，如果不能转换成上述类型则转换为字符串。handleRESTRequest中的outformat参数设置为“f”指定的类型。

http://<service-url>/exts/<extensionName>/near?location={x: -117.05, y: 34.11}&distance=2.5&&lookingFor=ATM&f=json

上述请求中，location参数将会被转换成json对象，distance被转换成数字，lookingFor将被转换成string。在触发handleRESTRequest方法之前，operationInput参数将被转换成如下json对象：

{  "location" : {x: -117.05, y: 34.11}, //JSON object  "distance" : 2.5, //number  "lookingFor" : "ATM" //string}

 

以上就是这节要说的内容，特别声明一下，本篇内容并非原创，大部分内容参考了这篇文章：

http://atlas.resources.ca.gov/arcgis/SDK/REST/extension.html