• Artykuł

        

SkyDrive dla programisty - Podstawowe pojęcia  Udostępnij na: Facebook

Tłumaczenie na podstawie SkyDrive core concets: Norbert Blandzi

Opublikowano: 2012-06-28

W tym odcinku poznasz podstawowe pojęcia, ograniczenia i zalecenia, związane z wykorzystaniem wirtualnego dysku SkyDrive w Twojej aplikacji. Sprawdź kod z interaktywnym SDK.

Przegląd katalogu SkyDrive

Aby wykorzystać API Live Connect w celu uzyskania informacji o głównych folderach użytkowników w katalogu SkyDrive, należy użyć polecenia me/skydrive lub USER_ID/skydrive. Poniżej znajduje się opis, jak należy nawiązać to połączenie:

  • w Representational State Transfer (REST) wykorzystaj metodę GET,
  • w JavaScript wykorzystaj funkcję WL.api, określając parametr metody "GET",
  • w C# do aplikacji Metro wykorzystaj metodę LiveConnectClient.Get,
  • w C# do aplikacji Windows Phone wykorzystaj metodę LiveConnectClient.GetAsync,
  • w Objective-C wykorzystaj metodę LiveConnectClient getWithPath,
  • w Javie wykorzystaj metodę LiveConnectClient.getAsync.

W odpowiedzi zostanie przesłany sformatowany obiekt JavaScript Object Notation (JSON). Dwie jego konstrukcje są godne uwagi: id struktury, która reprezentuje ID głównego folderu, i konstruktor upload_location, który reprezentuje lokalizację głównego folderu, do którego możesz wysyłać pliki, filmy i zdjęcia.

Jeżeli wydasz komendęme/skydrive/files lub USER_ID/skydrive/files, obiekt JSON, który jest zwrócony, będzie zawierał informację o wszystkich podfolderach, albumach i plikach, dostępnych w głównym folderze.

Od teraz możesz poruszać się po całym katalogu SkyDrive poprzez polecenie FOLDER_ID/files lub ALBUM_ID/files, gdzie FOLDER_ID lub ALBUM_ID reprezentują id obiektu, który odpowiada ID folderu lub albumu, znajdującego się gdzieś w katalogu.

Jako główny folder użytkownika SkyDrive możesz użyć struktury upload_location dla każdego folderu lub albumu, aby wysłać pliki do tego folderu lub albumu. Dodatkowo, możesz wykorzystać strukturę upload_location każdego pliku, zdjęcia, plików wideo lub audio do nadpisania zawartości tych plików, zdjęć, plików audio i wideo.

Poniżej znajduje komunikacja wyświetlanej zawartość folderu oraz wyświetlenie zawartości jednego z folderów:

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", 
            ...
        }
    ]
}

Uprawnienia obiektów

Użytkownicy mogą kontrolować, kto ma dostęp do pewnych obiektów z jego zasobu danych w SkyDrive. Do tych obiektów zaliczamy foldery, pliki, albumy, zdjęcia, pliki audio i wideo.

Uprawnienia obiektów w SkyDrive są dziedziczone z nadrzędnych folderów, począwszy od głównego folderu użytkownika katalogu SkyDrive.

Kiedy Twój kod tworzy lub uaktualnia obiekt w SkyDrive nie może ustawić lub zmienić uprawnień obiektu programowo. Jego uprawnienia dziedziczone są automatycznie. Jednak aplikacja może zezwolić na dzielenie się obiektem SkyDrive z wyznaczonymi użytkownikami do przeglądania lub przeglądania i edytowania folderu lub pliku. Oczywiście, użytkownik może zmienić uprawnienia obiektów przez interfejs użytkownika SkyDrive.

Twój kod nie może zmienić uprawnień obiektów, które ograniczyłyby dostęp, począwszy od głównego folderu użytkownika katalogu SkyDrive. Na przykład, jeżeli pewien folder pozwala każdemu na dostęp do jego zawartości, nie możesz zmienić uprawnień żadnego obiektu danego folderu, aby ograniczyć do nich dostęp.

Twój kod może pobrać link do folderu lub pliku, a następnie możesz dzielić się tym linkiem z innymi użytkownikami, dzięki czemu otrzymają oni bezpośredni dostęp do tych folderów i plików. Możliwe jest kilka typów linku m.in. embedded, read-only i read-write dla publicznych folderów i plików. Te linki będą działały wyłącznie dla użytkowników, mających dostęp do widoku tych plików.  

Udostępniamy także specjalne (uwierzytelnione) odnośniki do plików. Linki te działają niezależnie od praw dostępu do tych plików i powinny być tworzone wyłącznie wtedy, gdy użytkownik chce podzielić się folderem lub plikiem z określoną grupą ludzi. Używając tych linków, każdy może mieć wgląd na zawartość, którą wskazują, bez względu na prawa dostępu.

W celu uzyskania więcej informacji, sprawdź sekcję "Uzyskiwanie linków do folderów i plików" w artykule Foldery i pliki – modyfikacja i przenoszenie plików.

Pobieranie obiektów SkyDrive, współdzielonych z zalogowanym użytkownikiem

W celu skontrolowania wszystkich obiektów SkyDrive, które są współdzielone z zalogowanym użytkownikiem, wykorzystaj pole wl.contacts_skydrive, aby użyć metody GET dla /USER_ID/skydrive/shared, gdzie USER_ID jest albo "me" albo ID użytkownika, który wyraził na to zgodę. Oto przykład:

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

Pliki

Aby przesłać plik do SkyDrive, Twój kod może wykorzystywać operacje http, takie jak POST lub PUT. Możesz także wykorzystać MOVE i COPY, aby uniknąć pobierania, a potem wysyłania plików, które chcesz przenieść lub skopiować.

Gdy Twój kod przesyła plik, a plik z taką samą nazwą już istnieje w tej lokalizacji w SkyDrive, domyślnym zachowaniem SkyDrive jest nadpisanie istniejącego pliku. Aby istniejący plik nie został zastąpiony, dodaj nagłówek Overwrite i nadaj mu wartość false.

Użyj predefiniowanych nazw, aby umożliwić dostęp do niektórych folderów SkyDrive

W celu posiadania dostępu do pewnych folderów SkyDrive, możesz użyć predefiniowanych nazw zamiast jego ID. Użyj następujących predefiniowanych nazw, aby umożliwić dostęp do odpowiednich folderów w interfejsie użytkownika SkyDrive:

  • USER_ID/skydrive/camera_roll reprezentujący folder SkyDrive camera roll,
  • USER_ID/skydrive/my_documents reprezentujący folder Dokumenty (Documents),
  • USER_ID/skydrive/my_photos reprezentujący folder Zdjęcia (Pictures),
  • USER_ID/skydrive/public_documents reprezentujący folder Publiczny (Public).

W każdym wypadku zamień USER_ID, albo za pomocą "me", dla zalogowanego użytkownika, albo przez ID użytkownika, który wyraził na to zgodę.

Na przykład, odczytując właściwości folderu przez REST API, odwołanie się do ID folderu wygląda następująco:

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

Możesz także odczytać właściwości folderu przez REST API, odwołując się do predefiniowanych nazw folderów w ten sposób:

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

Zauważ, że aby przenieść albo skopiować plik do folderu z predefiniowaną nazwą, musisz wprowadzić tylko predefiniowaną nazwę jako wartość struktury docelowej. Tutaj przedstawiamy przykład, jak wywołać REST API, aby przenieść pliki do folderu Dokumenty:

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

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    destination: "my_documents"
}

Uzyskaj całkowitą oraz wolną pojemność wirtualnego dysku

W celu zdobycia informacji na temat dostępnej i niewykorzystanej pojemności w SkyDrive użyj metody GET do /me/skydrive/quota lub /USER_ID/skydrive/quota, gdzie USER_ID oznacza ID zarejestrowanego użytkownika. Oto przykład wykorzystania REST API:

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

Zwrócony obiekt JSON wygląda następująco:

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

W powyższym przykładzie struktura quota oznacza całkowitą, dostępną pojemność dysku użytkownika, podaną w bajtach. Struktura available oznacza pozostałą, niewykorzystaną pojemność również podaną w bajtach.

Dostępne formaty plików

Obecnie, SkyDrive obsługuje następujące formaty plików:

  • dokumenty (pliki Portable Document Format (PDF), dokumenty tekstowe, i dokumenty Microsoft Office),
  • zdjęcia (powszechne formaty grafiki; przesyłanie plików RAW nie jest obsługiwane),
  • wideo (H.264 i Windows Media Video (.wmv)),
  • audio (obsługiwane jest pobieranie pliku audio każdego typu i wysyłanie tylko plików typu Waveform Audio File Format (.wav)).

Oto pełna lista obsługiwanych rozszerzeń plików:

  • .3g2,
  • .3gp,
  • .ai,
  • .bmp,
  • .chm,
  • .doc,
  • .docm,
  • .docx,
  • .dot,
  • .dotx,
  • .epub,
  • .gif,
  • .jpeg,
  • .jpg,
  • .mp4,
  • .one,
  • .pdf,
  • .png,
  • .pot,
  • .potm,
  • .potx,
  • .pps,
  • .ppsm,
  • .ppsx,
  • .ppt,
  • .pptm,
  • .pptx,
  • .psd,
  • .tif,
  • .tiff,
  • .txt,
  • .xls,
  • .xlsb,
  • .xlsm,
  • .xlsx,
  • .wav,
  • .webp,
  • .wmv.

Wskazówki do aplikacji, współdziałających ze SkyDrive

Aplikacje, które współdziałają ze SkyDrive muszą być przystosowane do następujących reguł:

  • przesyłanie plików do SkyDrive następuje wyłącznie na wyraźne polecenie lub wybór użytkownika. Twoja aplikacja musi zawsze gwarantować to, że zapisanie jakiejkolwiek pliku na SkyDrive było świadomym działaniem użytkownika. Aplikacja nie może wysyłać plików automatycznie bez wyraźnego polecenia użytkownika.

Oto kilka przykładów odpowiednich aplikacji:

  • aplikacje wykorzystujące przyciski "Upload to SkyDrive" lub "Share on SkyDrive", które użytkownicy muszą nacisnąć przed każdym wysłaniem zdjęć, filmów, dokumentów oraz innych plików,
  • aplikacje edytujące dokumenty, które wymagają naciśnięcia na początku przycisku "Upload to SkyDrive", dzięki którym aplikacja może zachować dokument bez późniejszej interakcji z użytkownikiem.

Oto kilka przykładów niezgodnych aplikacji:

  • aplikacje, które automatycznie prześlą na SkyDrive każdy plik, dodany do wyznaczonych lokalizacji na urządzeniu użytkownika,
  • aplikacje, które automatycznie tworzą kopie zapasowe plików lub folderów na SkyDrive,
  • wykorzystuj SkyDrive do rzeczy, w których jest dobry. SkyDrive zawiera funkcje zarówno do przeglądania oraz edytowania dokumentów wysokiej jakości, jak i tworzenia i dzielenia się albumami zdjęć. Jeśli to możliwe, spraw, aby Twoja aplikacja wykorzystywała zalety tych funkcji. Aby wspomóc tą regułę, Live Connect APIs ograniczył liczbę formatów plików, które aplikacje mogą przesyłać na SkyDrive. Ogólnie rzecz biorąc, jeżeli Twoja aplikacja zapisuje pliki w formatach, obsługiwanych wyłącznie przez nią, to te pliki nie mogą znaleźć się na SkyDrive,
  • nie podważaj reputacji SkyDrive. Przez lata, w czasie których SkyDrive był dostępny, zdobył on zaufanie swoich użytkowników. Zachowanie tego zaufania jest istotne i Twoje aplikacje nie powinny go podważać, robiąc niespodziewane rzeczy w stosunku do użytkowników, w szczególności uważaj na przestrzeganie zasad prywatności.

Oto przykłady odpowiednich aplikacji:

  • aplikacje, które przesyłają dokumenty lub zdjęcia na SkyDrive, standardowo nadają prawa jedynie dla użytkownika,
  • aplikacje, które ostrzegają użytkowników, gdy wysyłają oni link do treści przechowywanej na SkyDrive, ponieważ każdy, kto otrzyma ten link może odczytać udostępnione pliki.  

Oto przykłady niezgodnych aplikacji:

  • aplikacje, które udostępniają publicznie każdy przesłany plik, bez jasnego poinformowania użytkowników.