Windows 商店應用中使用 SharePoint REST API

標籤：des   style   http   io   ar   os   使用   sp   java   

前面一篇我們介紹了 Office 365 REST API 的官方工具的使用，本篇我們來看一下 SharePoint REST API 本身的描述、結構和使用方法，以及一些使用經驗。

首先來看看SharePoint REST API 的概述：

      REST API 服務是在 SharePoint 2013 中被引入的，官方認為 REST API 服務可以媲美於現有的 SharePoint 用戶端物件模型。開發人員可以使用任何支援 REST Web 請求的技術（C#，javascript，java，oc 等等）以遠程方式與 SharePoint 資料進行互動。這也就意味著，開發人員可以使用 REST Web技術和標準開放資料協議（OData）文法從其 SharePoint 相關應用程式、解決方案和用戶端應用程式執行 CRUD 操作。而針對遠程 Web 或行動裝置 App，必須先獲得存取權限，才能使用 SharePoint 資料資源。

     在 REST API 出現之前，我們需要通過 client.svc 這個 WCF 服務來請求 SharePoint 的列表資料，而且僅限於擷取資料。資料的修改並沒有在這個服務中體現。而通過 REST API，我們可以完成前面提到的 CRUD 操作：使用OData 標準構造可實現 REST 的 HTTP 要求，對應到相應的要求方法，就可以對該資源進行讀取或操作了。例如使用 GET 方法取得資料，使用 POST 方法來建立資料，使用 PUT 或 MERGE 方法來更新資料，使用 DELETE 方法來刪除資料。

      REST API 預設會返回 Atom 格式的資料，不過我們也可以根據需求設定返回 JSON 格式的資料。我個人更喜歡處理 JSON 格式，JSON 資料轉換為 C# 的對象，有一個很棒的網站：http://json2csharp.com/。通過這個網站，我們可以把 JSON 資料直接轉換為 C# 對象，節省了很多編寫 C# 基礎代碼的時間。

接下來我們來看看 REST API 的結構組成：

      端點的基本URL是：https://server/site/_api ,它是所有 SharePoint REST API 的基礎，其中 server 代表格服務器的名稱，site 代表特定網站的名稱或者路徑。

      如果要訪問特定的網站集合，URL是：https://server/site/_api/site，如果要訪問特定的網站，URL則是：https://server/site/_api/web 。這兩種是最常用的 API ，還有幾種 API 能實現一些特定的功能，如：使用搜尋服務：https://server/site/_api/search，訪問使用者設定檔：http://server/site/_api/SP.UserProfiles.PeopleManager 等。

      下面我們以特定網站為例，來看一下 REST API 能完成哪些常見操作：

      （1）對列表和清單項目的操作

       列表：

       URL：http://<網站 URL>/web/lists(guid‘<列表 ID>‘) 或 http://<網站 URL>/web/lists/getbytitle(‘title of list‘)

       清單項目集合：

       URL：http://<網站 URL>/web/lists(guid‘<列表 ID>‘) /items 或 http://<網站 URL>/web/lists/getbytitle(‘title of list‘)/items

      指定 ID 的清單項目：

      URL：http://<網站 URL>/web/lists(guid‘<列表 ID>‘) /items(item id) 或 http://<網站 URL>/web/lists/getbytitle(‘title of list‘)/items(item id)

       如上 API 地址所示，我們可以通過List 本身的 GUID 或者 Title 來擷取List，或者List的項集合的資料。當需要向列表中插入新項時，我們需要使用清單項目集合 API，使用 POST 方法插入資料。而需要修改列表中某一項時，則需要使用指定清單項目 API，使用 MERGE 方法來更新資料。

       而涉及到資料修改時，我們需要把方法類型，如 POST，MERGE 等作為X-HTTP_Method 鍵的值添加到請求標題中。而且需要將請求表單摘要值作為 X-RequestDigest 的值傳遞進去。該值的擷取方式是：向 http://網站URL/_api/contextinfo
發送具有空本文的 POST 請求，並在 contextinfo 終結點返回的 XML 中提取 d:FormDigestValue 節點的值。還有就是標題中的 IF-MATCH 鍵的值，需要賦值為列表或清單項目的 etag 值。如果賦值為 “*”，則不會考慮並發問題。

       另外關於資料操作是需要 POST 的內容：

       更新時，必須包含 __metadata:type 和需要更新的欄位。其他不需要更新的欄位可以不加入。刪除時，URL指向該條記錄即可。添加時，URL指向記錄集合，POST內容應包含__metadata:type 和需要插入的必要欄位

      （2）對檔案和檔案夾的操作

       檔案：

       URL：http://<網站 URL>/_api/web/getfilebyserverrelativeurl(‘/<檔案夾名稱>/<檔案名稱>‘)

       檔案清單：

       URL：http://<網站 URL>/_api/web/getfolderbyserverrelativeurl(‘/<檔案夾名稱>‘)/files

       檔案夾：

       URL：http://<網站 URL>/_api/web/getfolderbyserverrelativeurl(‘/<檔案夾名稱>‘)

       通過以上 API 操作，我們可以完成檔案和檔案夾的讀取，上傳和修改等操作。

       當需要向文件庫插入文檔時，URL 是：http://<site url>/_api/web/GetFolderByServerRelativeUrl(‘/Shared Documents‘)/Files/add(url=‘a.txt‘,overwrite=true)，這樣，我們就把檔案以 a.txt 為存放名稱插入到了 Shared Documents 文件庫中。而文檔內容的上傳過程是：檔案讀取為 Stream，放入 POST 內容中。檔案還有其他很多中操作方式，如更新，簽出，簽入，刪除等。

      （3）對使用者、組和角色的操作

       組：

       URL：http://<網站 URL>/_api/web/sitegroups(<組 ID>)

       使用者：

       URL：http://<網站 URL>/_api/web/siteusers(@v)[email protected]=‘<登入名稱>‘

       角色：

       URL：http://<網站 URL>/_api/web/roledefinitions(<角色定義 ID>)

      （4）對使用者設定檔的操作

       URL：http://<網站 url>/_api/sp.userprofiles.peoplemanager

      （5）對欄位的操作

       URL：http://<網站 url>/_api/web/fields(‘<欄位 id>‘) 或 http://<網站 url>/_api/web/lists(guid‘<列表 id>‘)/fields(‘<欄位 id>‘)

       上面我們介紹了列表，檔案夾等類型 API 的地址構造，接下來我們看看這些請求地址中允許的查詢參數都有哪些：       

       （1）$select 參數

       如 SQL 中 Select 的使用方法，這裡的 $select 也是確定請求返回的結果中需要包含哪些欄位，使用方法是：_api/web/lists/getByTitle(‘Books‘)/items?$select=Author,Title,ISBN，這樣我們就會在取得Books這個列表時，只擷取作者，書名和ISBN三個有效欄位。

       （2）$filter 參數

       如 SQL 中 Where 的使用方法，這裡的 $filter 是用來篩選資料的篩選條件，使用方法是：_api/web/lists/getByTitle(‘Books‘)/items?$filter=Author eq ‘Mark Twain‘，這樣我們就能取到 Books 列表中，Author 為 Mark Twain 的資料。

       （3）$expand 參數

       這個參數用於指定返回聯結列表中的哪些投射欄位。使用方法是：_api/web/lists/getByTitle(‘Books‘)/items?$select=Title,PublishedBy/Name&$expand=PublishedBy，這裡的投射欄位是 PublishedBy。

       （4）$top 參數

       這個參數使用者指定返回結果集中的前N項，使用方法是：_api/web/lists/getByTitle(‘Books‘)/items?$top=2，這樣我們就會返回這個結果集中的前兩項（如不足兩項則返回全部資料）。

       （5）$skip 參數

       這個參數用於在結果集中跳過指定數量的項，而返回剩餘的項。使用方法是：_api/web/lists/getByTitle(‘Books‘)/items?$skip=2，這樣我們就會在返回結果中跳過前兩項而返回其餘的項，如結果不足兩項，則返回空結果集。

       （6）$orderby 參數

       這個參數用於對結果集進行排序，如 SQL 中使用方法，分為升序和降序兩種方式，以 asc 和 desc 關鍵字來標識。使用方法是：_api/web/lists/getByTitle(‘Books‘)/items?$orderby=ID desc。這樣我們返回的結果集，就會以 ID 為標準來降序排列。 

       下面這張表，涵蓋了 SharePoint REST API 中幾乎所有的查詢條件和數字、字元等的比較關鍵字。例如 $filter=Author eq ‘Mark Twain‘，就是篩選 Author 等於 Mark Twain 的項，而 Author ne ‘Mark Twain‘，則是篩選不等的項。這是針對字串的比較操作，而針對數位則包括  lt（小於）、le（小於等於）、gt（大於）、ge（大於等於）、eq（等於）和 ne（不等於）。還有針對日期和時間的比較符，見表中解釋。

        

       最後還涉及到一個授權的問題，如前面所說，遠端存取都需要先授權才能訪問資源。我們可以通過 OAuth 授權的方式來完成應用授權和身分識別驗證。將獲得的 OAuth 存取權杖加入到請求標題中。這裡我們不做詳細介紹了。關於 API本身的使用過程，和其他 API 沒什麼差異，這裡就不做詳細介紹了。就是一個發出請求，獲得返回結果（Atom或JSON），然後解析結果的過程。

       這樣我們就把 SharePoint REST API 的構成和基本的使用方法介紹完了，希望對大家在 Windows 商店應用中使用 SharePoint REST API 有所協助，謝謝。

       

 

 

 

 

     

Windows 商店應用中使用 SharePoint REST API