• 發行項

本文章是由機器翻譯。

Windows 市集

將 OneDrive 整合至您的 Windows 市集應用程式

Tony Champion

下載代碼示例

你不能去很遠今天不運行的對話有關雲計算發展。 公共、 私人上,-或關閉-處所，雲產品現在進來所有形狀和大小。 但當談到以消費為基礎的應用程式，處理使用者的檔，機會是你將重點放在像微軟另祭。

微軟另，最近更名，為消費者提供一個方便的方法來存儲、 共用和訪問他們的個人檔從任何地方的任何設備。 另現在充分融入所有微軟平臺上，和它是與當前使用中的大多數其他平臺相容。 文檔、 照片、 視頻和許多其他類型的檔可以方便地共用、 同步或跨設備訪問。 所以，如果你正在構建一個應用程式，涉及到使用者檔，將另集成到您的應用程式應該是一個重要特徵。

如果你正在構建 Windows 商店應用程式，您將自動免費得到某種程度的另能力。 在 Windows 8.1，你會發現 Windows 商店另 app 以及桌面集成檔案系統，其中包括執行檔打開選取器和檔保存選取器合同中。 這意味著如果您使用檔打開或將採摘保存在您的應用程式中，使用者將自動打開或保存檔到他另帳戶的能力。 同樣是真實的打開和保存檔對話方塊中的桌面應用程式。

然而，如果你有點想更多的控制權，這種互動的工作方式會發生什麼呢？ 如果你想在不同的格式，顯示使用者的資料或處理的上載或下載多個檔在後臺嗎？ 為了解決這種情況下，Microsoft 提供了一個 API，可以從任何平臺允許開發者將另集成到其解決方案中訪問。 這篇文章探討了 API，看著什麼參與在您的 Windows 應用商店應用程式中使用這個 API。

引入活 SDK

訪問的內容中另被通過生活的 SDK。 在其核心，住 SDK 是基於 JSON，其餘的 Api，可以在任何平臺上消耗的集合。 住 SDK 使用單點登錄 Windows 存儲和 Windows Phone 存儲應用程式和其他平臺的 OAuth 2.0 身份驗證。 為了説明開發人員創建使用另成功應用程式，微軟還發佈了特定于用戶端的 Sdk。 目前有微軟的 Windows 和 Windows Phone 平臺 Sdk，以及為 Android 和 iOS 的 Sdk。 所有這些 Sdk 的連結可以發現在 msdn.microsoft.com/onedrive/dn630256。 活的 SDK 還可以通過 NuGet (nuget.org/packages/LiveSDK)。

另，關於生活的 SDK 的主要作用是允許程式設計訪問的檔和資料夾在使用者的帳戶內。 這裡是由 SDK 提供的基本服務：

  • 資料夾層次結構中導航
  • 創建和刪除新的資料夾
  • 讀取和修改資料夾屬性
  • 上傳和下載檔案
  • 讀取和修改檔案屬性
  • 複製和移動檔和資料夾
  • 獲取共用檔和資料夾的連結
  • 在檔和資料夾上設置許可權

我使用Visual Studio2013年更新 2 和活 SDK 版本 5.6，探討如何在 XAML 編寫的一個 8.1 Windows 應用商店應用程式中使用的 SDK。 與大多數平臺上的用戶端特定 Sdk 的可用性，相同的概念可以容易地遷移到的語言和您所選擇的平臺。

開發應用程式與活 SDK

你可以開始開發應用程式在使用活 SDK 之前，有幾個管家專案到位址。 因為活著的 SDK 並不是核心Windows SDK的一部分，你必須下載活 SDK，然後添加對它從您的應用程式的引用。 要添加的引用，只是用滑鼠右鍵按一下您在Visual Studio2013年的解決方案並選擇增加參考。 住 SDK 可以發現在 Windows 8.1 擴展部分的參考管理器，如中所示圖 1。

增加參考住 SDK
圖 1 增加參考住 SDK

預設情況下，Windows 8.1 商店應用程式具有在其 appxmanifest 中啟用的互聯網 （用戶端） 功能。 這是一個所需的能力，為使用活 SDK，您的專案必須已啟用它。 要驗證或啟用此功能，在設計器中打開您的專案的 appxmanifest，請確保在功能選項卡中選中了互聯網 （用戶端）。

一旦生活 SDK 已經添加到您的專案，你會發現整個 SDK 在 Microsoft.Live 命名空間中。 然而，在這一點上使用 SDK 將產生一個 null 物件引用錯誤。 這是因為您必須註冊您的應用程式提供現場服務之前您可以訪問另。 根據你正在開發發展的平臺，可以為此在幾個方面。 一個 Windows 應用商店應用程式，你只是您的應用程式將與 Windows 存儲關聯。 最直接的方法來做到這一點是在Visual Studio中使用嚮導。

若要啟動嚮導，右擊解決方案資源管理器中的存儲專案並選擇存儲 |將應用程式與存儲相關聯。 該嚮導將打開帶有說明的您需要才能繼續。 選擇下一步會提示您登錄到微軟帳戶與 Windows 存儲相關聯，（如果你不是已經在簽署)。 你也可能要經過第二次核查過程中，如接收授權碼通過文本消息到與您的帳戶關聯的電話號碼。 一旦你完成了登錄過程，你會看到與您的帳戶相關聯的所有保留的應用程式名稱的清單，如中所示圖 2。 如果這是一個新的應用程式，您也可以保留一個新的應用程式名稱，從該螢幕。 一旦你有了要關聯您的應用程式的名稱，選擇下一步將帶你到一個摘要螢幕，按一下副教授將完成該過程。

將保留的名稱與應用程式相關聯
圖 2 將保留的名稱與應用程式相關聯

您的應用程式現在是設置並且準備好開始使用活 SDK。

訪問使用者的資料

啟用另集成到您的應用程式的第一步獲得訪問使用者的資訊的能力。 如前文所述，住 SDK 使用 0Auth 2.0 的授權。 然而，有幾個要點需要考慮除了簡單地對您的應用程式進行身份驗證。

另適當使用如果你熟悉開發和部署 Windows 商店應用程式，你知道有很多指引，詳細說明你能做什麼和不能做在您的應用程式內。 另添加其自己的準則，還必須考慮到集。

限制的主要原因是為了防止你破壞了使用者的信賴，在另。 當使用者將她的個人資訊存儲的中心源，她有對固有的信任源或她不會用它。 通過您的應用程式訪問另，使用者擴大這種信任向您的應用程式。 所以，如果您的應用程式開始刪除使用者的資料未經她的同意或知識，你破壞這種信任，不僅影響使用者的感知的應用程式，但也另她悟性。 為此原因，你必須格外小心中如何您的應用程式與交互另，特別是在執行更新或刪除使用者資訊的函數。 這些指南的說明可以找到在 bit.ly/1rQ8iXK。

使用單點登錄使用時住的 SDK 在 Windows 應用商店應用程式，Microsoft 建議您利用其單一登入 (SSO) 功能。 只是作為生活的 sdk，將 SSO 添加到您的應用程式涉及到一些額外的要求，像隱私權聲明和帳戶設置面板。 步驟，將必要的元件添加到您的應用程式的全部細節，可以發現在 bit.ly/TJvTxB。

您的應用程式為 SSO 準備後，登錄到該使用者帳戶是使用 LiveAuthClient 類的一個實例。 LiveAuthClient 具有一個 LoginAsync 方法，將會使用到 Windows 8.1 設備目前在簽署微軟帳戶的憑據。 如果登錄成功，返回的 LiveLoginResult 物件將包含一個 LiveConnectSession 實例，將用於對住 SDK 的所有調用。 以下操作會使使用者登錄並返回會話物件：

LiveAuthClient authClient = new LiveAuthClient();
LiveLoginResult authResult = 
  await authClient.LoginAsync(new List<string>() {
  "wl.signin",
  "wl.basic", "wl.skydrive", "wl.skydrive_update" });
if (authResult.Status == LiveConnectSessionStatus.Connected)
{
  // Add code to handle session held in the Session property
}

作用域你可能注意到了像"wl.signin"在前面的代碼範圍的使用。 當您的應用程式給使用者帳戶登錄時，它必須確定需要哪種類型的訪問。 如果您嘗試使用的 API，您還沒有請求訪問的部分，你的嘗試將失敗。 對於 Windows 應用商店應用程式，這是比試圖使用Windows SDK你還沒請准入包 appxmanifest 的功能部分中的某些部分沒有什麼不同。

這篇文章中的示例將使用只有四個作用域。 Wl.signin 範圍允許您利用您應該在應用 Windows 商店應用程式中使用的 SSO 行為。 Wl.basic 範圍可以訪問一些常見使用者有關的資訊。

對於應用程式另，有你需要關心的只有兩個其他作用域：wl.skydrive 和 wl.skydrive_update。 因為名稱可能表明，wl.skydrive 是必要的閱讀和流覽到另一個使用者帳戶的訪問。 如果您的應用程式需要能夠將檔上傳、 創建或刪除資料夾，或更改物件的屬性，則使用 wl.skydrive_update 範圍。 此範圍還授予你的讀取權限到另，所以你不需要在訪問清單中包括 wl.skydrive 和 wl.skydrive_update 的作用域。

為了保持向後相容的應用程式使用先前的品牌，沒有換另範圍名稱。 然而，我不會驚訝地看到了兩個其他作用域使用另的品牌出現在將來版本的 API。

因為生活 SDK 涵蓋了很多更多的地面比只是另，那裡很多其他我不會在這篇文章位址的範圍。 你可以找到一個完整的描述性清單在 msdn.microsoft.com/library/dn631845。

獲得使用者同意使用者第一次運行應用程式的請求訪問到他的另一個考慮，他將會提示以授予該應用程式許可權到作用域登錄調用中提供。 圖 3 在 Windows 應用商店應用程式顯示一個提示，這種的一個示例。 一旦使用者授予的許可權，他不會再次提示，只要範圍清單中不會改變。 如果應用程式請求額外的功能的 API 的更新版本，將會再次提示許可權的使用者。

請求訪問另使用者同意
圖 3 請求訪問另使用者同意

物件上另

另 API 認為一切都是物件。 是否資料夾、 照片或試算表中，一切都存儲在另一組類似的屬性，他們分享的 API 呼叫。 每個物件的屬性的集合，並且可能有一個子物件的集合。 在這篇文章中，我將重點放在物件的類型是：資料夾、 檔、 相冊和照片。 你會發現與他們的描述可用物件的完整清單，請在使用 msdn.microsoft.com/library/dn631843。

一旦您的應用程式從 LiveAuthClient 的 LoginAsync 方法獲得 LiveConnectionSession 的一個實例，該屆會議實例可用於創建類的實例 LiveConnectClient，其中包含所有你將使用與另進行交互的 API 呼叫。 下面的示例演示創建實例的 LiveConnectClient 和使用者的 root 資料夾物件，可以使用檢索查詢另"我 / skydrive"路徑：

public async Task<object> GetRootFolder()
{
  LiveConnectClient client = new LiveConnectClient(_session);
  LiveOperationResult liveOpResult = 
    await client.GetAsync("me/skydrive");
  dynamic dynResult = liveOpResult.Result;
  return dynResult;
}

此代碼使用 dynamic 關鍵字在運行時創建了基礎的 JSON 格式字串的類實例。 雖然這是快速和容易使用，請的記住有一些限制，您可能會遇到那將需要更多的正式的類結構。

從 GetAsync 方法返回的結果將包含所有請求的物件的屬性。 圖 4 JSON formattted 字串的示例，返回使用者的根資料夾中的顯示。

圖 4 從資料夾物件查詢返回的 JSON

{
  "id": "folder.abced3a35e6d1b",
  "from": {
    "name": null,
    "id": null
  },
  "name": "SkyDrive",
  "description": "",
  "parent_id": null,
  "size": 2957188732,
  "upload_location": 
    "https://apis.live.net/v5.0/folder.abced3a35e6d1b/files/",
  "comments_count": 0,
  "comments_enabled": false,
  "is_embeddable": false,
  "count": 25,
  "link": "https://onedrive.live.com?cid=abced3a35e6d1b",
  "type": "folder",
  "shared_with": {
    "access": "Just me"
  },
  "created_time": null,
  "updated_time": "2014-06-13T18:00:54+0000",
  "client_updated_time": "2012-10-22T19:50:04+0000"
}

查詢時內另，它可以創建更具體的查詢非常有用。 例如，以下將返回所有子物件的根目錄中：

LiveOperationResult liveOpResult = await client.GetAsync("me/skydrive/files");

這包括資料夾和檔，也可能很多資料。

如果你想要看到只有清單中此目錄的照片嗎？ 這可以通過使用篩選器查詢參數。 另 API 支援幾種不同類型的查詢參數加上的篩選，如限制、 偏移量和搜索。 參數允許您獲取所需資料你需要的和他們限制不僅必須下載的資料量的處理返回的資料所需的代碼量。

例如，以下查詢返回在根目錄下，節省您不必編寫代碼，以分離出的照片從資料夾中只有一個的照片清單：

LiveOperationResult liveOpResult =
  await client.GetAsync("me/skydrive/files?filter=photos");

查詢參數和它們的使用的完整清單可以在找到 msdn.microsoft.com/library/dn631842。

使用資料夾

如果你要使用任何一種檔案系統，一個邏輯的地方開始是用的資料夾結構。 查詢時為一個資料夾，您可以使用兩種不同類型的識別碼：像我這樣一個友好的路徑 / skydrive 或一個資料夾 id，看上去有點像 folder.abcde86dfb3a35e6d1b.ABCDED3A35E6D1B!532。 如果您想要查詢的一個資料夾的子物件的清單，您可以將追加"/ 檔"的路徑。 例如，以下將返回清單中的所有檔、 資料夾和為一個給定的資料夾 id 的專輯：

LiveOperationResult liveOpResult =
  await client.GetAsync("folder.abcde86dfb3a35e6d1b.ABCDED3A35E6D1B!532/files");

另包含兩種類型的資料夾物件：資料夾和專輯。 一張專輯可說是一種特殊類型的資料夾中發現了另一個使用者的根目錄中。 專輯可以包含照片和視頻，以及一個資料夾結構和其他檔。

它是重要的是理解一個資料夾和一張專輯，之間的區別，因為下面的查詢將返回只有資料夾在您的根目錄中，忽略所有的專輯。 這可能會導致意外的結果：

LiveOperationResult liveOpResult =
  await client.GetAsync("me/skydrive/files?filter=folders");

若要返回資料夾和相冊，使用篩選器值的"資料夾，專輯"。

前面的查詢允許您通過讓孩子每個資料夾的資料夾流覽整個資料夾結構的另一個使用者帳戶。 這篇文章的相關的下載包含樣例應用程式，MyPhotoAlbum，一個包含兩個頁面的 XAML Windows 應用商店應用程式。 第一頁，FolderPage，允許您流覽你的目錄結構和顯示 GridView 中的結果。 所有活著的 SDK 調用被包裝在 OneDriveDataProvider 類中。

圖 5 用作篩選值顯示用於遍歷資料夾結構中的當前資料夾 id 通過和使用"資料夾，專輯"的方法。 如果資料夾 id 不存在，該方法預設的根目錄。

圖 5 GetFolderItems 方法

public async Task<List<object>> 
  GetFolderItems(string path, string filter)
{
  if (_session == null)
  {
    await InitProvider();
  }
  if (String.IsNullOrEmpty(path))
  {
    path = "me/skydrive";
  }
  if (!String.IsNullOrEmpty(filter))
  {
    filter = "?filter=" + filter;
  }
  LiveConnectClient client = new LiveConnectClient(_session);
  LiveOperationResult liveOpResult =
    await client.GetAsync(path + "/files" + filter);
  dynamic dynResult = liveOpResult.Result;
  return new List<object>(dynResult.data);
}

圖 6 顯示在 FolderPage 中返回的結果的一個示例。 選擇一個子資料夾將導航到相同的 FolderPage，作為參數使用的子資料夾。 這將允許導航堆疊保留的背功能搬回了的資料夾結構。

FolderPage
圖 6 FolderPage

如果你所要求使用的 wl.skydrive_update 範圍的更新存取權限，您還可以創建和刪除資料夾使用 API。 一個資料夾包含您可以創建或更改的只有三個屬性：名稱、 說明和 sort_by。 當創建一個資料夾，您必須指定的父目錄，可以通過路徑或 id，並且提供 JSON 陣列，在最低限度，一個名稱。 以下是用於創建一個新的資料夾所需的 JSON 示例：

{
 "name": "My Favorite Photos",
 "description": "A folder full of my favorite photos."
}

SDK 處理這通過 LiveConnectClient 的 PostAsync 方法。 圖 7 顯示用來創建新的資料夾的方法。

圖 7 CreateFolder 方法

public async Task<bool> CreateFolder(string path, string name)
{
  try
  {
    var folderData = new Dictionary<string, object>();
    folderData.Add("name", name);
    LiveConnectClient liveClient = new LiveConnectClient(_session);
    LiveOperationResult operationResult =
      await liveClient.PostAsync(path, folderData);
    dynamic result = operationResult.Result;
    return true;
  }
  catch (LiveConnectException exception)
  {
    return false;
  }
}

刪除資料夾做使用的 DeleteAsync 方法，也可以用來刪除檔。 它是重要的是記住關於維護另的完整性和小心使用任何刪除功能：

LiveOperationResult operationResult = await liveClient.DeleteAsync(path);

處理檔案

雖然 GetAsync 方法將返回一個檔的屬性，它不會返回該檔本身。 得到從另一個檔的唯一方法是通過下載它。 住 SDK 為 Windows 應用商店應用程式處理這種通過創建一個下載背景任務，處理非同步而不陷入設備下載。 下面的代碼可以用於從另下載檔案：

try
{
  LiveConnectClient liveClient = new LiveConnectClient(_session);
  LiveDownloadOperation op =
    await liveClient.CreateBackgroundDownloadAsync(filePath);
  var result = await op.StartAsync();
  // Handle result
}
catch
{
  // Handle errors
}

一旦返回後臺下載操作，則必須通過調用 StartAsync 方法的 LiveDownload 啟動­操作實例。

類似于下載一個檔，唯一的方法來添加或更新在另一個檔是把它上傳。 為上傳一個檔，您的應用程式必須已要求寫存取權限通過使用 wl.skydrive_update 範圍。 CreateBackgroundUploadAsync 方法將一個資料夾路徑、 檔案名、 包含檔和覆蓋選項的流。 如果一個檔已存在，覆蓋選項也可以覆蓋原始檔案或它可以保持原始檔案和重命名正在上載的新檔。 作為與該資料夾更新功能，照顧時使用此功能不無意中破壞的檔。 以下是如何上傳檔的示例：

try
{
  LiveConnectClient liveClient = new LiveConnectClient(_session);
  LiveUploadOperation op = await liveClient.CreateBackgroundUploadAsync(
    path, filename, fileStream, OverwriteOption.Rename);
  var result = await op.StartAsync();
  // Handle result
}
catch
{
  // Handle errors
}

再上傳一個檔，它是重要的是確保使用者有足夠的空間為新的檔。 您可以通過使用 GetObjectAsync 方法中的路徑"我/skydrive/配額"驗證可用空間的量。 這將返回兩個屬性，配額，並且可用，讓你計算使用者的帳戶中剩餘的位元組數。

有兩個附加功能在 API 中派上用場在處理檔時。 如果你想要的檔的一個副本，你可以下載該檔，然後將上載它使用一個不同的名稱。 但是，這可能會使用大量的頻寬為一個相當簡單的操作。 此外，如果您想要將整個資料夾複製或移動到不同的父資料夾的子資料夾嗎？ 代碼和頻寬來做使用下載和上載會使這種操作相當繁瑣。 為了解決這些函數，另 API 具有移動和複製命令：MoveAsync 和 CopyAsync。 兩個帶兩個參數：物件 — — 檔或資料夾 — — 移動到的目標路徑。 圖 8 顯示了用來複製檔的方法。

圖 8 複製檔

public async Task<bool> CopyObject(string path, string destination)
{
  if (_session == null)
  {
    await InitProvider();
  }
  try
  {
    LiveConnectClient liveClient = new LiveConnectClient(_session);
    LiveOperationResult operationResult =
      await liveClient.CopyAsync(path, destination);
    return true;
  }
  catch (LiveConnectException exception)
  {
    return false;
  }
}

總結

只有這麼多的 API 可以覆蓋在一篇文章。 活的 SDK 中包含更多的功能，尤其是對照片和視頻處理。 如果你在看另融入您的解決方案，它將非常有益探索這些額外的功能。 Microsoft 創建了另發展中心給你一個單一訪問點，一切有關另 API 在 dev.onedrive.com。

無論您構建 Windows 應用商店應用程式，應用 Windows Phone 商店應用程式或需要對使用者的檔存取權限的任何其他平臺的應用程式，添加另是一個偉大的方式，通過給予他訪問的檔那件事最他將您的應用程式集成到使用者的日常生活。 所以，當你建立你偉大的使用者體驗，一定要包括另。

Tony Champion 是冠軍 DS 的總統，是微軟最有價值球員，是活躍在演講、 博客寫手，和作者社區。他認為在一個博客 tonychampion.net ，可以通過電子郵件在到達 tony@tonychampion.net。

感謝以下的微軟技術專家對本文的審閱：咪咪 Sasouvanh
咪咪 Sasouvanh 是一個內容的開發人員在 Microsoft 作業系統組內容團隊中，寫關於另發展和 Azure 智慧的系統服務，除其他外。 她花時間與家人、 園藝、 和素描，