Windows app
摺疊目錄
展開目錄

從應用程式存取 Microsoft OneDrive 時的一般工作

本主題說明從應用程式存取使用者的 OneDrive 內容時,如何執行一般工作。

周遊 OneDrive 目錄

若要使用 Live Connect API 來取得使用者在 OneDrive 目錄中最上層資料夾的相關資訊,您可以對 me/skydriveUSER_ID/skydrive 發出要求。呼叫的方法如下:

  • 在表象化狀態轉換 (REST) 中,使用 GET
  • 在 JavaScript 中,使用 WL.api 函式,指定 "GET" 的 method 參數。
  • 在 C# 中,使用 LiveConnectClient.GetAsync 方法。
  • 在 Objective-C 中,使用 LiveConnectClient getWithPath 方法。
  • 在 Java 中,使用 LiveConnectClient.getAsync 方法。

在傳回的 JavaScript 物件標記法 (JSON) 格式物件中,必須注意兩個很重要的結構:id 結構,表示最上層資料夾的資料夾識別碼;upload_location 結構,表示可以將檔案、相片、影片及音訊上傳到最上層資料夾的位置。

如果要求 me/skydrive/filesUSER_ID/skydrive/files,傳回的 JSON 格式物件中只會包含使用者最上層資料夾中所有子資料夾、子相簿以及檔案的資訊。

從該處,使用 FOLDER_ID/filesALBUM_ID/files 發出要求,就可以周遊使用者的整個 OneDrive 目錄;其中 FOLDER_IDALBUM_ID 分別代表對應到目錄中任何一處之資料夾識別碼或相簿識別碼的 id 結構。

如同使用者的最上層 OneDrive 資料夾一樣,您可以針對任何資料夾或相簿使用 upload_location 結構,以將檔案上傳到該資料夾或相簿。此外,您還可以對任何檔案、相片、影片或音訊使用 upload_location 結構,覆寫檔案、相片、影片或音訊的內容。

例如,以下是使用者的 OneDrive 目錄在概念上看起來的樣子。

GET https://apis.live.net/v5.0/me/skydrive?access_token=ACCESS_TOKEN
---
200 OK
{
    "id": "folder.a6b2a7e8f2515e5e", 
    ...
    "upload_location": "https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e/files",
    ...
    "type": "folder",
    ...
}
---
GET https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e/files?access_token=ACCESS_TOKEN
---
200 OK
{
    "data": [
        {
            "id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110", 
            ...
            "upload_location": "https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110/files/"
            ...
            "type": "folder",
            ...
        }, {
            "id": "photo.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131", 
            ...
            "upload_location": "https://apis.live.net/v5.0/photo.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/content/", 
            ...
            "type": "photo",
            ...
        }, {
            "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!119", 
            ...             
            "upload_location": "https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!119/content/", 
            ...
            "type": "file", 
            ...
        }
    ]
}

頁首

取得與登入的使用者分享的 OneDrive 物件清單

若要探索與登入的使用者分享的所有 OneDrive 物件,請使用 wl.contacts_skydrive 領域對 /USER_ID/skydrive/shared 發出 GET 要求,其中 USER_IDme 或同意的使用者的使用者識別碼。這裡提供一個範例。

GET https://apis.live.net/v5.0/me/skydrive/shared?access_token=ACCESS_TOKEN

附註  OneDrive API 不支援建立、更新或刪除與登入的使用者分享的資料夾檔案。應用程式只能操作已登入使用者所擁有的檔案。

重要  我們不支援上傳檔案到共用資料夾的第三方應用程式。

頁首

使用易記名稱存取特定 OneDrive 資料夾

若要存取特定 OneDrive 資料夾,您可以使用易記名稱而不使用資料夾識別碼。使用下列易記名稱來存取 OneDrive UI 中這些對應的資料夾:

  • USER_ID/skydrive/camera_roll 代表 [OneDrive 手機相簿] 資料夾。
  • USER_ID/skydrive/my_documents 代表 [文件] 資料夾。
  • USER_ID/skydrive/my_photos 代表 [圖片] 資料夾。
  • USER_ID/skydrive/public_documents 代表 [公用] 資料夾。

在任一種情況下,使用已登入使用者的 me 或任何其他已同意使用者的使用者識別碼來取代 USER_ID

例如,若要讀取 [文件] 資料夾內容,使用 REST API 呼叫資料夾識別碼,就像這樣。

GET https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110?access_token=ACCESS_TOKEN

但是,您也可以使用 REST API 呼叫資料夾易記名稱來讀取 [文件] 資料夾內容,就像這樣:

GET https://apis.live.net/v5.0/me/skydrive/my_documents?access_token=ACCESS_TOKEN

附註  若要將檔案移動或複製到具有易記名稱的資料夾,您僅提供易記名稱做為 destination 結構的值。這裡是如何呼叫 REST API 以便將檔案移動到 [文件] 資料夾的範例。

MOVE https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "destination": "my_documents"
}

頁首

取得使用者最近使用的文件清單

若要取得使用者最近使用過的 OneDrive 文件清單,請使用 wl.skydrive 領域,對 /USER_ID/skydrive/recent_docs 發出 GET 要求,其中 USER_IDme 或同意的使用者的使用者識別碼。這裡提供一個範例。

GET https://apis.live.net/v5.0/me/skydrive/recent_docs?access_token=ACCESS_TOKEN

頁首

取得使用者的全部及剩餘的 OneDrive 儲存配額

若要取得使用者在 OneDrive 中可用及未使用的儲存空間相關資訊,請對 /me/skydrive/quota/USER_ID/skydrive/quota 發出 GET 呼叫,其中 USER_ID 是已登入使用者的識別碼。這裡是使用 REST API 的範例。

GET https://apis.live.net/v5.0/me/skydrive/quota?access_token=ACCESS_TOKEN

傳回的 JSON 格式物件看起來就像這樣。

{
    "quota": 26843545600,
    "available": 26805319016
}

在前述的範例中,quota 欄位是使用者的總可用儲存空間 (位元組);available 欄位是使用者的剩餘未使用儲存空間 (同樣是位元組)。

提示  上傳檔案之前,請讓您的應用程式進行檢查,來確定有足夠的可用儲存空間。例如,您的應用程式可以取得檔案的大小 (位元組),接著將它與 available 欄位中的位元組數相比較。如果檔案大小大於 available 欄位,您的應用程式便不應嘗試上傳檔案。如果您的應用程式仍嘗試上傳檔案,則上傳要求將會失敗,而 OneDrive 將傳回下列錯誤。

{
    "error": {
        "code": "resource_quota_exceeded", 
        "message": "The user has reached his or her storage quota limit."
    }
}

頁首

顯示 OneDrive 項目的預覽

若要顯示 OneDrive 中項目的預覽,請對 /skydrive/get_item_preview?type=TYPE&url=URL 發出 GET 要求。選擇性的 type 查詢字串參數是下列其中一個值:

  • thumbnail
  • small (取得最高 100 × 100 像素預覽)
  • album (最高 200 × 200)
  • normal (最高 800 × 800)

必要的 url 查詢字串參數是一個分享連結,連至 OneDrive 中的項目。這裡提供兩個範例,一個使用較長的 OneDrive URL,另一個則使用較短的 sdrv.ms URL (sdrv.ms 是 OneDrive 專屬的短網址服務)。

GET https://apis.live.net/v5.0/skydrive/get_item_preview?type=normal&url=https%3A%2F%2Fskydrive.live.com%2Fredir.aspx%3Fcid%3Da6b2a7e8f2515e5e%26amp%3Bresid%3DA6B2A7E8F2515E5E!132%26amp%3Bparid%3DA6B2A7E8F2515E5E!110%26amp%3Bauthkey%3D!ACuMMo37Ju8_xw0x

GET https://apis.live.net/v5.0/skydrive/get_item_preview?type=normal&url=http%3A%2F%2Fsdrv.ms%2FLTIvcyx

請注意下列事項:

  • 若要發出 get_item_preview 要求,您不需要要求任何領域或提供存取權杖。
  • 如果項目不是相片,而且預覽已與該項目相關聯,即會顯示縮圖預覽並忽略 type 參數 (即使提供了此參數也一樣)。
  • "Location" 回應標頭有可連至項目預覽的 responseStatus 值為 " 302 Found" 時,才表示回應成功。
  • 如果特殊大小的預覽不存在,則會顯示可用的次大預覽。如果沒有任何預覽與該項目相關聯,即會傳回 404 (找不到) 錯誤。
  • 您可以利用下列三種方式之一來取得分享的連結:
    • ITEM_ID/shared_read_link 發出 GET 要求,其中 ITEM_ID 是 OneDrive 項目的識別碼。此處提供一個範例。
      GET https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/shared_read_link?access_token=ACCESS_TOKEN
      
      
      您可以在 JSON 格式回應物件的 link 結構中找到分享的連結值。
    • 在 OneDrive UI 中,選取該項目,然後按一下 [分享]。按一下 [取得連結],然後在 View only 旁邊,按一下 [Create]。OneDrive 會顯示分享的連結值,您可以在 get_item_preview 要求中使用這個值。這個值看起來應該會像這樣:https://onedrive.live.com/redir.aspx?cid=a6b2a7e8f2515e5e&resid=A6B2A7E8F2515E5E!132&parid=A6B2A7E8F2515E5E!110&authkey=!ACuMMo37Ju8_xw0x
    • 在 OneDrive UI 中,選取該項目,然後按一下 [分享]。按一下 [張貼至 Twitter]、遵循螢幕上的指示操作,然後按一下 [張貼]。新建立的 Twitter 張貼文章會包含分享的連結值,您可以在 get_item_preview 要求中使用這個值。這個值看起來應該會像這樣:http://1drv.ms/LTIvcyx
  • url 查詢字串參數的值必須是以 URL 編碼的。例如,針對冒號 (":") 字元使用 %3A、針對斜線 ("/") 字元使用 %2F、針對問號 ("?") 使用 %3F,以及針對 "&" 字元使用 %26。

頁首

 

 

顯示:
© 2016 Microsoft