26、深入探索SharePoint服务的消费：URL命令与RPC方法

深入探索SharePoint服务的消费：URL命令与RPC方法

1. URL命令的使用

URL命令通过HTTP GET请求从SharePoint服务器获取XML结果。其调用形式为在特定格式的地址中以查询字符串指定命令，格式如下：

http://server/subsite/_vti_bin/owssvr.dll?Cmd=cmdname&param=value&param=value ...

URL命令不会更改内容数据库，因此无需身份验证。而RPC协议与之类似，但使用HTTP POST发送请求，可包含身份验证信息并更改内容。

以下是一些常见的SharePoint URL命令及其用途：
| 命令 | 参数 | 用途 |
| — | — | — |
| dialogview | dialogview, location, FileDialogFilterValue | 打开用于在文档库中打开或保存文件的对话框视图，或打开保存文件到文档库时使用的自定义属性表单 |
| Display | List, XMLDATA | 对列表执行数据库查询并返回XML或HTML |
| DisplayPost | PostBody, URLBase | 渲染分配给PostBody参数的协作应用标记语言（CAML） |
| ExportList | List | 以CAML格式导出列表的架构 |
| GetProjSchema | 无 | 请求网站的XML架构 |
| GetUsageBlob | BlobType | 获取网站使用情况的信息 |
| HitCounter | Page, Image, Custom, Digits | 在页面的img元素中渲染点击计数器 |
| RenderView | List, View, URLBase | 请求列表视图的内容 |

URL命令还接受一些可选参数来修改返回结果，如下表所示：
| 参数 | 用途 |
| — | — |
| FileDialogFilterValue | 为视图设置过滤器，并根据文件扩展名（如 .doc, .ppt, 或*.xls）从文档库返回指定类型的所有文件列表 |
| FilterFieldn | 指定数据库中字段的名称，n为整数，仅受数据库表允许的字段数量或URL字段允许的长度限制 |
| FilterValuen | 指定用于过滤字段的字符串值，n为整数，仅受URL字段允许的长度限制 |
| SortField | 指定用于排序的字段名称 |
| SortDir | 指示升序（asc）或降序（desc）排序顺序 |
| Using | 指定包含CAML的特定文件，供服务器评估和渲染 |

2. 获取GUID

URL命令的List和View参数是SharePoint内部使用的唯一标识符（GUID）。由于没有URL命令可从名称获取GUID，因此需要使用SharePoint对象模型或Web服务来获取这些值。以下是在三种不同场景下获取列表和视图GUID的方法：

2.1 使用SharePoint对象

在SharePoint内部工作时，可通过SharePoint对象模型获取GUID。以下是获取列表和视图GUID的示例代码：

' Requires: Imports Microsoft.SharePoint.Webcontrols
Function GetListGuid(ByVal lName As String) As String
    Try
        ' Get the web from the current context.
        Dim web As SPWeb = SPControl.GetContextWeb(context)
        ' Get the list by name.
        Dim lst As SPList = web.Lists(lName)
        ' Get the GUID of the list.
        Dim guid As System.Guid = lst.ID
        ' Format the GUID as a string.
        Return ("{" & guid.ToString & "}")
    Catch ex As Exception
        Debug.Write(ex.Message)
        Return ""
    End Try
End Function

Function GetViewGuid(ByVal lName As String, _
  ByVal vName As String) As String
    Try
        ' Get the web from the current context.
        Dim web As SPWeb = SPControl.GetContextWeb(context)
        ' Get the view by name.
        Dim view As SPView = web.Lists(lName).Views(vName)
        ' Get the GUID of the list.
        Dim guid As System.Guid = view.ID
        ' Format the GUID as a string.
        Return ("{" & guid.ToString & "}")
    Catch ex As Exception
        Debug.Write(ex.Message)
        Return ""
    End Try
End Function

2.2 使用Web服务（.NET）

Lists Web服务的GetList方法返回包含列表GUID的XML描述。可使用SelectSingleNode从XML中提取ID属性，示例代码如下：

' Requires a web reference to the Lists.asmx.
Function GetListGUID(ByVal lName As String) As String
    Dim xn As Xml.XmlNode, lws As New Lists.Lists
    Try
        ' Get the XML result from the web service.
        xn = lws.GetList(lName)
        ' Get the GUID (it's the ID attribute of the root element).
        Return xn.SelectSingleNode("//@ID").InnerText
    Catch ex As Exception
        Return ""
    End Try
End Function

' Requires a web reference to the Views.asmx.
Function GetViewGUID(ByVal lName As String, ByVal vName As String) As String
    Dim xn As Xml.XmlNode, vws As New Views.Views
    Try
        ' Get the XML result from the web service.
        xn = vws.GetViewCollection(lName)
        ' Get the GUID (it's the Name attribute)
        ' where @DisplayName matches the view name.
        Return xn.SelectSingleNode("//*[@DisplayName='" & _
          vName & "']/@Name").InnerText
    Catch ex As Exception
        Return ""
    End Try
End Function

2.3 使用Web服务（VBA）

从VBA获取GUID与使用.NET的Web服务类似，但XML对象和错误处理与.NET不同，示例代码如下：

' Requires web reference to Lists.asmx.
Function GetListGUID(lName As String) As String
    On Error Resume Next
    Dim lws As New clsws_Lists
    Dim xn As IXMLDOMNodeList, guid As String
    ' Get the list.
    Set xn = lws.wsm_GetList(lName)
    ' Extract the GUID (it's the ID attribute).
    guid = xn(0).selectSingleNode("//@ID").Text
    ' Return "" if not found.
    If Err Then guid = ""
    ' Return the GUID.
    GetListGUID = guid
End Function

' Requires web reference to Views.asmx.
Function GetViewGUID(lName As String, vName As String) As String
    On Error Resume Next
    Dim vws As New clsws_Views
    Dim xn As IXMLDOMNodeList, guid As String
    ' Get the list's views.
    Set xn = vws.wsm_GetViewCollection(lName)
    ' Extract the GUID (it's the Name attribute).
    guid = xn(0).selectSingleNode("//*[@DisplayName='" & _
      vName & "']/@Name").Text
    ' Return "" if not found.
    If Err Then guid = ""
    ' Return the GUID.
    GetViewGUID = guid
End Function

3. 执行URL命令

URL命令可作为页面上渲染的链接的一部分使用。例如，以下链接显示列表的架构：

<a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=ExportList&List={70F9FF01-15E5-4129-A370-9A31090204E9}">Show list schema</a>

也可以在代码中使用.NET XML对象获取结果XML，示例代码如下：

' .NET: Use URL protocol to get a list's XML.
Function GetListSchema(ByVal lName As String) As String
    Dim xdoc As New Xml.XmlDocument
    Dim guid As String = GetListGUID(lName)
    ' Create a reader for the URL.
    Dim xr As New Xml.XmlTextReader("http://wombat1/_vti_bin/owssvr.dll" & _
      "?Cmd=ExportList&List=" & guid)
    ' Load the response.
    xdoc.Load(xr)
    ' Return the XML as a string.
    Return xdoc.OuterXml
End Function

VBA代码如下：

' VBA: Use URL protocol to get a list's XML.
Function GetListSchema(ByVal lName As String) As String
    Dim guid As String, xdoc As New DOMDocument
    guid = GetListGUID(lName)
    ' Load the response.
    xdoc.Load ("http://wombat1/_vti_bin/owssvr.dll" & _
      "?Cmd=ExportList&List=" & guid)
    ' Return the XML as a string.
    GetListXML xdoc.Text
End Function

可以通过实验URL命令来获得正确的参数组合。通常在代码中使用之前，在浏览器的地址栏或作为HTML链接编写命令会更容易。例如：

<a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List={70F9FF01-15E5-4129-A370-9A31090204E9}&XMLDATA=TRUE">Display list XML (minimal)</a><br>
<a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List={70F9FF01-15E5-4129-A370-9A31090204E9}&XMLDATA=TRUE&Query=*">Display list XML (full)</a>

对于复杂查询，使用Web服务或RPC通常更容易。

4. 使用RPC

SharePoint远程过程调用（RPC）方法提供了另一种远程更改SharePoint站点和获取内容的方式。RPC方法与前面讨论的URL命令类似，但使用HTTP POST而不是GET发送请求。

当希望使用协作应用标记语言（CAML）而不是通过Web服务方法来编写更改或查询时，可以使用RPC方法。CAML是一种使用XML而不是像Visual Basic .NET这样的过程编程语言来对SharePoint进行编程的声明性方法，具有以下优点：
- RPC方法可以作为内容包含在网页上，而不是作为服务器端代码。
- 用户可以在不安装Web部件或其他代码的情况下，使用CAML编写和运行自己的查询。
- SharePoint模板和描述使用CAML，因此理解它有助于创建自定义站点定义。
- RPC比Web服务的开销更小。

不过，CAML是一项需要学习的技能，而且相当高级。对于不使用Web部件自定义SharePoint站点，RPC是合理的选择。

以下是一些常见的SharePoint RPC方法及其用途：
| 方法 | 参数 | 用途 |
| — | — | — |
| Cltreq | UL, STRMVER, ACT, URL | 执行Web讨论操作，如添加、编辑或删除与网页或存储在文档库中的文档相关的讨论 |
| Delete | ID, List, NextUsing, owsfileref | 删除列表中的项目 |
| DeleteField | List, Field, owshiddenversion | 从列表中删除字段 |
| DeleteList | List, NextUsing | 删除列表 |
| DeleteView | List, View | 删除视图 |
| ImportList | Title, RootFolder, ListSchema | 根据指定的XML架构创建列表 |
| ModListSettings | List, OldListTitle, NewListTitle, Description, ReadSecurity, WriteSecurity, SchemaSecurity | 更改列表的属性 |
| NewField | List, FieldXML, AddToDefaultView, owshiddenversion | 向指定列表添加新字段 |
| NewList | ListTemplate, Description, displayOnLeft, VersioningEnabled, GlobalMtgDataList, AllowMultiVote, showUsernames | 创建指定类型的列表，如联系人、讨论或调查 |
| NewViewPage | List, PageURL, DisplayName, HiddenView | 向列表添加新的视图页面 |
| NewWebPage | 无 | 在文档库中创建新的Web部件页面或新的基本页面 |
| ReorderFields | List, ReorderedFields | 更改列表中字段在数据输入表单上的显示顺序 |
| Save | ID, List, NextUsing | 保存新列表或保存对现有列表的修改 |
| SiteProvision | CreateLists | 向现有的SharePoint站点添加默认列表集 |
| UpdateField | List, FieldXML, owshiddenversion | 修改列表中现有字段的架构 |

5. 为RPC准备页面

由于RPC方法可以更改内容，因此POST请求必须包含用户信息，以便SharePoint对方法进行身份验证和授权。为此，在网页上执行RPC命令需要采取以下特殊步骤：
1. 向页面添加FormDigest控件。
2. 创建一个表单元素，其中包含要执行的方法，并将其内容POST到 http://server/site/_vti_bin/owssvr.dll 。
3. 创建一个客户端脚本，在表单提交之前将FormDigest控件的值插入到表单中。
4. 添加一个提交按钮来提交表单。

例如，创建一个用于测试RPC命令的页面 RPCDemo.aspx ，在页面头部添加以下脚本：

<!-- This directive registers the FormDigest WebControl -->
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
Assembly="Microsoft.SharePoint, Version=11.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" %>
<html dir="ltr">
<HEAD>
<!-- Add this script to include user info in the CAML -->
<script type="text/javascript" language="JavaScript">
function InsertSecurityValidation(oForm)
{
    var sFormDigest = '<SetVar Name="_ _REQUESTDIGEST">' +
      oForm.elements["_ _REQUESTDIGEST"].value + "</SetVar>\n";
    var oPostBody = oForm.elements["PostBody"];
    var rePattern = /<\/Method>/g;
    oPostBody.value = oPostBody.value.replace(rePattern, sFormDigest + "</Method>");
}
</script>
</HEAD>

然后在SharePoint生成的关闭表单标签之后添加以下表单：

<!-- SharePoint web part zones omitted here -->
<\form>
<!-- Form used to post RPC commands to SharePoint -->
<form class="ms-formbody" method="post"
  action="http://wombat1/_vti_bin/owssvr.dll"
  onsubmit="InsertSecurityValidation(this);"
  target="result" >
  <!-- This control provides user information -->
  <SharePoint:FormDigest runat="server"/>
  Enter CAML containing RPC methods and click Run to see the result:
  <input type="hidden" name="Cmd" value="DisplayPost" />
  <!-- Source for CAML -->
  <textarea name="PostBody" style="width=100%;height=200">
  </textarea>
  <br>
  <input type="submit" value="Run" />
  <input type="reset" value="Clear" />
  <br>
  Result:
  <!-- Target for results -->
  <IFRAME name="result" src="::blank.htm" style="width=100%;height=200"/>
</form>

一旦对结果满意，可以使用隐藏输入控件将CAML硬编码到新网页上，如下所示：

<!-- Embedded RPC -->
<form class="ms-formbody" method="post"
  action="http://wombat1/_vti_bin/owssvr.dll"
  onsubmit="InsertSecurityValidation(this);"
  target="_blank" >
  <!-- This control provides user information -->
  <SharePoint:FormDigest runat="server"/>
  Click Run to see the result in a pop-up window.
  <input type="hidden" name="Cmd" value="DisplayPost" />
  <!-- Source for CAML -->
  <input type="hidden" name="PostBody" value="
      <Method ID='0,DisplayPost'>
          <SetList Scope='Request'>Lists</SetList>
          <SetVar Name='View'>EnumLists</SetVar>
          <SetVar Name='Cmd'>DisplayPost</SetVar>
          <SetVar Name='XMLDATA'>TRUE</SetVar>
    </Method>" />
  <br>
  <input type="submit" value="Run" />
</form>

别忘了在新页面的头部添加 InsertSecurityValidation 脚本。这个示例将结果显示在新的弹出窗口中（ target="_blank" ），而不是在页面的内联框架中。

6. 常见RPC任务

以下是一些常见的使用RPC执行的任务示例，在这些示例中，需要将提供的列表和视图的GUID替换为自己站点的值。

6.1 识别列表

RPC方法通过列表的GUID来识别其作用的列表。可以通过调用DisplayPost方法并将View参数设置为EnumLists，通过RPC获取站点中所有列表的GUID，示例如下：

<Method ID="0,DisplayPost">
  <SetList Scope="Request">Lists</SetList>
  <SetVar Name="View">EnumLists</SetVar>
  <SetVar Name="Cmd">DisplayPost</SetVar>
  <SetVar Name="XMLDATA">TRUE</SetVar>
</Method>

找到所需列表的GUID后，在SetList元素中指定该值。例如，以下方法导出公告列表：

<Method ID="0,ExportList">
  <SetList Scope="Request">{41D7D046-1E0A-4FB2-A096-C063D210D552}</SetList>
  <SetVar Name="Cmd">ExportList</SetVar>
</Method>

6.2 组合多个方法

使用Batch元素可以在单个POST请求中组合两个或多个RPC方法。例如，以下CAML向公告列表添加两个项目：

<ows:Batch Version="6.0.2.5608" OnError="Return">
  <Method ID="Anouncement1">
    <SetList>{41D7D046-1E0A-4FB2-A096-C063D210D552}</SetList>
    <SetVar Name="ID">New</SetVar>
    <SetVar Name="Cmd">Save</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#Title">Announcement Title1</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#Body">Announcement text</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#Expires">2005-09-14T00:00:00Z</SetVar>
  </Method>
  <Method ID="Announcement2">
    <SetList>{41D7D046-1E0A-4FB2-A096-C063D210D552}</SetList>
    <SetVar Name="ID">New</SetVar>
    <SetVar Name="Cmd">Save</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#Title">Announcement Title2</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#Body">Announcement text</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#Expires">2005-12-18T00:00:00Z</SetVar>
  </Method>
</ows:Batch>

Batch元素的OnError属性决定了如果其中一个方法失败时的处理方式。Return设置会使方法在发生错误时立即停止；Continue设置会使SharePoint跳过有错误的方法并继续执行下一个方法。

6.3 查询列表

使用Display方法对列表执行查询并仅返回特定的字段集。例如，以下查询使用过滤条件 introduced=2000 从列表中返回三个字段（注意字段名称区分大小写）：

<Method ID="0,Display">
  <SetList Scope="Request">{5E6561D4-7048-45AB-BFA1-2D1991BAF3B1}</SetList>
  <SetVar Name="Cmd">Display</SetVar>
  <SetVar Name="XMLDATA">False</SetVar>
  <SetVar Name="Query">name Title introduced</SetVar>
  <SetVar Name="FilterField1">introduced</SetVar>
  <SetVar Name="FilterValue1">2000</SetVar>
</Method>

对于需要过滤或排序的查询，也可以指定定义这些条件的视图。例如，以下查询返回由列表视图指定的列表中的项目：

<Method ID="0,Display">
  <SetList Scope="Request">{5E6561D4-7048-45AB-BFA1-2D1991BAF3B1}</SetList>
  <SetVar Name="Cmd">Display</SetVar>
  <SetVar Name="XMLDATA">False</SetVar>
  <SetVar Name="View">{21E03766-D0CF-4942-B2C0-DF4E3706DD50}</SetVar>
</Method>

6.4 创建列表

使用NewList方法在站点上创建新的列表或文档库。ListTemplate参数决定了创建的列表类型（具体类型可参考相关文档）。

通过以上介绍，我们详细了解了如何使用URL命令和RPC方法来消费SharePoint服务，包括获取GUID、执行命令以及完成常见任务等方面。这些技术为开发人员和管理员提供了强大的工具，以满足不同的SharePoint使用需求。

深入探索SharePoint服务的消费：URL命令与RPC方法

7. 不同方法的对比与选择建议

在使用SharePoint服务时，URL命令和RPC方法各有特点，以下是对它们的详细对比以及选择建议：

对比项	URL命令	RPC方法
请求方式	HTTP GET	HTTP POST
是否需要身份验证	否（不更改内容数据库）	是（可更改内容）
数据交互方式	以查询字符串指定命令获取XML结果	使用CAML编写更改或查询
适用场景	简单查询，获取只读信息	复杂操作，如创建、删除、修改列表等
技术难度	较低，易于在浏览器地址栏或HTML链接中使用	较高，需要学习CAML
性能开销	相对较小	比Web服务开销小，比URL命令大

选择建议：
- 如果只是进行简单的查询，获取列表的基本信息，如显示列表架构、获取列表的XML数据等，URL命令是一个不错的选择，它简单易用，无需身份验证。
- 当需要进行复杂的操作，如创建列表、删除列表项、修改字段等，并且希望使用声明性的CAML语言来编写操作逻辑时，RPC方法更为合适。虽然学习成本较高，但它提供了更强大的功能和更灵活的操作方式。

8. 实际应用案例分析

以下通过一个具体的实际应用案例，展示如何综合运用URL命令和RPC方法来满足业务需求。

假设我们要开发一个SharePoint应用，实现对一个项目列表的管理，包括显示项目列表、添加新项目和删除项目等功能。

8.1 显示项目列表

使用URL命令的Display方法来显示项目列表的基本信息。在页面上添加一个链接，点击链接即可获取列表的XML数据：

<a href="http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List={项目列表GUID}&XMLDATA=TRUE">Display project list XML</a>

在代码中，可以使用.NET XML对象获取并处理这些数据：

Function GetProjectListXML() As String
    Dim xdoc As New Xml.XmlDocument
    Dim guid As String = "{项目列表GUID}"
    Dim xr As New Xml.XmlTextReader("http://wombat1/_vti_bin/owssvr.dll?Cmd=Display&List=" & guid & "&XMLDATA=TRUE")
    xdoc.Load(xr)
    Return xdoc.OuterXml
End Function

8.2 添加新项目

使用RPC方法的Batch元素来添加新项目。首先，准备好包含新项目信息的CAML代码：

<ows:Batch Version="6.0.2.5608" OnError="Return">
  <Method ID="NewProject1">
    <SetList>{项目列表GUID}</SetList>
    <SetVar Name="ID">New</SetVar>
    <SetVar Name="Cmd">Save</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#项目名称">项目名称1</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#项目描述">项目描述1</SetVar>
    <SetVar Name="urn:schemas-microsoft-com:office:office#开始日期">2024-01-01T00:00:00Z</SetVar>
  </Method>
</ows:Batch>

然后，在页面上创建一个表单，将CAML代码作为表单数据提交：

<form class="ms-formbody" method="post"
  action="http://wombat1/_vti_bin/owssvr.dll"
  onsubmit="InsertSecurityValidation(this);"
  target="_blank" >
  <SharePoint:FormDigest runat="server"/>
  <input type="hidden" name="Cmd" value="DisplayPost" />
  <input type="hidden" name="PostBody" value='
    <ows:Batch Version="6.0.2.5608" OnError="Return">
      <Method ID="NewProject1">
        <SetList>{项目列表GUID}</SetList>
        <SetVar Name="ID">New</SetVar>
        <SetVar Name="Cmd">Save</SetVar>
        <SetVar Name="urn:schemas-microsoft-com:office:office#项目名称">项目名称1</SetVar>
        <SetVar Name="urn:schemas-microsoft-com:office:office#项目描述">项目描述1</SetVar>
        <SetVar Name="urn:schemas-microsoft-com:office:office#开始日期">2024-01-01T00:00:00Z</SetVar>
      </Method>
    </ows:Batch>' />
  <input type="submit" value="Add Project" />
</form>

8.3 删除项目

使用RPC方法的Delete元素来删除项目。准备好包含删除项目信息的CAML代码：

<Method ID="0,Delete">
  <SetList Scope="Request">{项目列表GUID}</SetList>
  <SetVar Name="ID">{项目ID}</SetVar>
  <SetVar Name="Cmd">Delete</SetVar>
</Method>

同样，在页面上创建一个表单，将CAML代码作为表单数据提交：

<form class="ms-formbody" method="post"
  action="http://wombat1/_vti_bin/owssvr.dll"
  onsubmit="InsertSecurityValidation(this);"
  target="_blank" >
  <SharePoint:FormDigest runat="server"/>
  <input type="hidden" name="Cmd" value="DisplayPost" />
  <input type="hidden" name="PostBody" value='
    <Method ID="0,Delete">
      <SetList Scope="Request">{项目列表GUID}</SetList>
      <SetVar Name="ID">{项目ID}</SetVar>
      <SetVar Name="Cmd">Delete</SetVar>
    </Method>' />
  <input type="submit" value="Delete Project" />
</form>

9. 总结与展望

通过对SharePoint服务的URL命令和RPC方法的深入学习，我们了解到这些技术为SharePoint的开发和管理提供了丰富的功能和灵活的操作方式。URL命令适用于简单的信息获取，而RPC方法则更适合复杂的操作和数据修改。

在实际应用中，我们可以根据具体的业务需求选择合适的方法，并且可以将它们结合使用，以实现更强大的功能。同时，需要注意的是，RPC方法使用的CAML语言需要一定的学习成本，开发人员需要掌握其基本语法和使用方法。

展望未来，随着SharePoint技术的不断发展，可能会出现更多更便捷的服务消费方式，同时对安全性和性能的要求也会越来越高。开发人员需要不断学习和掌握新的技术，以更好地满足业务需求。

以下是一个使用mermaid绘制的流程图，展示了在实际应用中选择URL命令和RPC方法的决策过程：

graph TD
    A[业务需求] --> B{操作类型}
    B -->|简单查询| C[URL命令]
    B -->|复杂操作| D[RPC方法]
    C --> E[获取信息]
    D --> F[编写CAML代码]
    F --> G[准备表单提交]
    G --> H[执行操作]

通过这个流程图，我们可以更清晰地看到在不同业务需求下如何选择合适的方法来消费SharePoint服务。