Kopiuj plik
Operacja Copy File kopiuje obiekt blob lub plik do pliku docelowego na koncie magazynu.
Dostępne w wersji 2015-02-21 lub nowszej.
Dostępność protokołu
| Włączony protokół udziału plików | Dostępne |
|---|---|
| SMB |
|
| NFS |
|
Żądanie
Żądanie można skonstruować Copy File w następujący sposób. Zalecamy użycie protokołu HTTPS.
Począwszy od wersji 2013-08-15, możesz określić sygnaturę dostępu współdzielonego dla pliku docelowego, jeśli znajduje się on na tym samym koncie co plik źródłowy. Począwszy od wersji 2015-04-05, możesz również określić sygnaturę dostępu współdzielonego dla pliku docelowego, jeśli znajduje się na innym koncie magazynu.
| Metoda | Identyfikator URI żądania | Wersja PROTOKOŁU HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Zastąp składniki ścieżki wyświetlane we własnym identyfikatorze URI żądania, w następujący sposób:
| Składnik ścieżki | Opis |
|---|---|
myaccount |
Nazwa konta magazynu. |
myshare |
Nazwa udziału plików. |
mydirectorypath |
Opcjonalny. Ścieżka do katalogu nadrzędnego. |
myfile |
Nazwa pliku. |
Aby uzyskać szczegółowe informacje na temat ograniczeń nazewnictwa ścieżek, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.
Parametry identyfikatora URI
W identyfikatorze URI żądania można określić następujące dodatkowe parametry:
| Parametr | Opis |
|---|---|
timeout |
Opcjonalny. Parametr limitu czasu jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji Azure Files. |
Nagłówki żądań
W poniższej tabeli opisano wymagane i opcjonalne nagłówki żądań:
| Nagłówek żądania | Opis |
|---|---|
Authorization |
Wymagane. Określa schemat autoryzacji, nazwę konta i podpis. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage. |
Date lub x-ms-date |
Wymagane. Określa dla żądania godzinę w formacie uniwersalnego czasu koordynowanego (UTC). Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage. |
x-ms-version |
Wymagane dla wszystkich autoryzowanych żądań. Określa wersję operacji do użycia dla tego żądania. Ta operacja jest dostępna tylko w wersji 2015-02-21 lub nowszej. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage. |
x-ms-meta-name:value |
Opcjonalny. Określa pary nazw/wartości skojarzone z plikiem jako metadane. Jeśli nie określono par nazw/wartości, operacja kopiuje metadane ze źródłowego obiektu blob lub pliku do pliku docelowego. Jeśli określono co najmniej jedną parę nazw/wartości, plik docelowy jest tworzony z określonymi metadanymi, a metadane nie są kopiowane ze źródłowego obiektu blob lub pliku. Nazwy metadanych muszą być zgodne z regułami nazewnictwa identyfikatorów języka C#. Należy pamiętać, że metadane plików określone za pośrednictwem Azure Files nie są dostępne z poziomu klienta SMB. |
x-ms-copy-source:name |
Wymagane. Określa adres URL pliku źródłowego lub obiektu blob o długości do 2 kibibajtów (KiB). Aby skopiować plik do innego pliku na tym samym koncie magazynu, możesz użyć klucza współużytkowanego, aby autoryzować plik źródłowy. Jeśli kopiujesz plik z innego konta magazynu lub kopiujesz obiekt blob z tego samego konta magazynu lub innego konta magazynu, musisz autoryzować plik źródłowy lub obiekt blob przy użyciu sygnatury dostępu współdzielonego. Jeśli źródło jest publicznym obiektem blob, do wykonania operacji kopiowania nie jest wymagana autoryzacja. Możesz również określić plik w migawki udziału jako źródło kopiowania. Oto kilka przykładów adresów URL obiektów źródłowych:
|
x-ms-lease-id:<ID> |
Wymagane, jeśli plik docelowy ma aktywną dzierżawę. Dostępne dla wersji 2019-02-02 lub nowszej. Identyfikator dzierżawy określony dla tego nagłówka musi być zgodny z identyfikatorem dzierżawy pliku docelowego. Jeśli żądanie nie zawiera identyfikatora dzierżawy lub identyfikator jest nieprawidłowy, operacja kończy się niepowodzeniem z kodem stanu 412 (Warunek wstępny nie powiodło się). Jeśli ten nagłówek jest określony, a plik docelowy nie ma obecnie aktywnej dzierżawy, operacja kończy się niepowodzeniem z kodem stanu 412 (Warunek wstępny nie powiodło się). |
x-ms-file-permission-copy-mode: { source ¦ override } |
Opcjonalny. Dostępne dla wersji 2019-07-07 lub nowszej. Określa zachowanie kopiowania deskryptora zabezpieczeń pliku:
|
x-ms-file-permission |
Wymagane, jeśli x-ms-file-permission-copy-mode określono wartość override i x-ms-file-permission-key nie jest określona. Dostępne dla wersji 2019-07-07 lub nowszej. To uprawnienie jest deskryptorem zabezpieczeń pliku określonego w języku SDDL (Security Descriptor Definition Language). Możesz użyć tego nagłówka, jeśli rozmiar uprawnień to 8 kibibajtów (KiB) lub mniej. W przeciwnym razie można użyć polecenia x-ms-file-permission-key. Jeśli zostanie określony, musi mieć listę właścicieli, grup i uznaniowych kontroli dostępu (DACL). Należy pamiętać, że można określić tylko jeden z x-ms-file-permission elementów lub x-ms-file-permission-key . |
x-ms-file-permission-key |
Wymagane, jeśli x-ms-file-permission-copy-mode określono wartość override i x-ms-file-permission nie jest określona. Dostępne dla wersji 2019-07-07 lub nowszej. Ten nagłówek określa klucz uprawnienia do ustawienia dla pliku. Ten klucz można utworzyć przy użyciu Create Permission operacji .Należy pamiętać, że można określić tylko jeden z x-ms-file-permission elementów lub x-ms-file-permission-key . |
x-ms-file-copy-ignore-readonly |
Opcjonalny. Dostępne dla wersji 2019-07-07 lub nowszej. Ta wartość logiczna określa, czy ReadOnly atrybut w wcześniej istniejących plikach docelowych powinien być przestrzegany. Jeśli jest to true, operacja kopiowania zakończy się pomyślnie. W przeciwnym razie poprzedni plik w miejscu docelowym z zestawem atrybutów ReadOnly powoduje niepowodzenie operacji kopiowania. |
x-ms-file-attributes |
Opcjonalny. Dostępne dla wersji 2019-07-07 lub nowszej. Ten nagłówek określa atrybuty systemu plików, które mają być ustawione w pliku docelowym. Zobacz listę dostępnych atrybutów. Możesz użyć wartości , source aby skopiować atrybuty z pliku źródłowego do pliku docelowego. Możesz użyć wartości none , aby wyczyścić wszystkie atrybuty w pliku docelowym. |
x-ms-file-creation-time |
Opcjonalny. Dostępne dla wersji 2019-07-07 lub nowszej. Ten nagłówek określa właściwość czasu tworzenia w formacie UTC, aby ustawić plik docelowy. Możesz użyć wartości , source aby skopiować czas tworzenia z pliku źródłowego do pliku docelowego. |
x-ms-file-last-write-time |
Opcjonalny. Dostępne dla wersji 2019-07-07 lub nowszej. Ten nagłówek określa właściwość czasu ostatniego zapisu w formacie UTC, aby ustawić w pliku docelowym. Możesz użyć wartości , source aby skopiować czas ostatniego zapisu z pliku źródłowego do pliku docelowego. |
x-ms-file-copy-set-archive |
Opcjonalny. Dostępne dla wersji 2019-07-07 lub nowszej. Ta wartość logiczna określa, czy Archive atrybut powinien być ustawiony niezależnie od wartości nagłówka x-ms-file-attributes . |
x-ms-client-request-id |
Opcjonalny. Udostępnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-KiB rejestrowanym w dziennikach podczas konfigurowania rejestrowania. Zdecydowanie zalecamy używanie tego nagłówka do korelowania działań po stronie klienta z żądaniami odbieranymi przez serwer. Aby uzyskać więcej informacji, zobacz Monitorowanie Azure Blob Storage. |
x-ms-file-change-time: { <DateTime> ¦ source } |
Opcjonalny. Wersja 2021-06-08 lub nowsza. Właściwość czasu ZMIANY CZASU UTC dla pliku sformatowana w formacie ISO 8601. Wartość może source służyć do kopiowania czasu zmiany z pliku źródłowego do pliku docelowego. Domyślny sygnatura czasowa to czas żądania. |
x-ms-file-request-intent |
Wymagane, jeśli Authorization nagłówek określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że wartość Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action powinna zostać udzielona, jeśli zostaną one uwzględnione w zasadach RBAC przypisanych do tożsamości, która jest autoryzowana przy użyciu nagłówka Authorization . Dostępne dla wersji 2022-11-02 lub nowszej. |
x-ms-allow-trailing-dot: { <Boolean> } |
Opcjonalny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w adresie URL żądania powinna być przycinana, czy nie. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych. |
x-ms-source-allow-trailing-dot: { <Boolean> } |
Opcjonalny. Wersja 2022-11-02 lub nowsza. Wartość logiczna określa, czy końcowa kropka obecna w źródłowym adresie URL powinna być przycinana, czy nie. Ten nagłówek powinien być określony tylko wtedy, gdy źródło kopiowania jest plikiem platformy Azure. Ten nagłówek nie jest obsługiwany dla żadnego innego typu źródła kopiowania. Aby uzyskać więcej informacji, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych. |
Treść żądania
Brak.
Reakcja
Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.
Kod stanu
Operacja zakończona powodzeniem zwraca kod stanu 202 (Zaakceptowano).
Aby uzyskać informacje o kodach stanu, zobacz Stan i kody błędów.
Nagłówki odpowiedzi
Odpowiedź na tę operację zawiera następujące nagłówki. Odpowiedź zawiera również dodatkowe standardowe nagłówki HTTP. Wszystkie nagłówki standardowe są zgodne ze specyfikacją protokołu HTTP/1.1.
| Nagłówek odpowiedzi | Opis |
|---|---|
ETag |
Jeśli operacja kopiowania zostanie ukończona, zawiera ETag wartość pliku docelowego. Jeśli operacja kopiowania nie zostanie ukończona, zawiera ETag wartość pustego pliku utworzonego na początku operacji. |
Last-Modified |
Zwraca datę/godzinę zakończenia operacji kopiowania do pliku docelowego. |
x-ms-request-id |
Jednoznacznie identyfikuje wykonane żądanie. Ten nagłówek służy do rozwiązywania problemów z żądaniem. Aby uzyskać więcej informacji, zobacz Rozwiązywanie problemów z operacjami interfejsu API. |
x-ms-version |
Wskazuje wersję Azure Files, która jest używana do wykonania żądania. |
Date |
Wartość daty/godziny UTC wskazująca godzinę, w której usługa wysłała odpowiedź. |
x-ms-copy-id: <id> |
Zawiera identyfikator ciągu dla tej operacji kopiowania. Użyj polecenia Get File lub Get File Properties , aby sprawdzić stan tej operacji kopiowania lub przekazać polecenie , aby Abort Copy File anulować oczekującą operację kopiowania. |
x-ms-copy-status: <success ¦ pending> |
Wskazuje stan operacji kopiowania z następującymi wartościami: - success: Operacja kopiowania zakończyła się pomyślnie.- pending: Operacja kopiowania jest nadal w toku. |
x-ms-client-request-id |
Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli znajduje się w żądaniu, a wartość wynosi co najwyżej 1024 widoczne znaki ASCII.
x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek nie będzie obecny w odpowiedzi. |
Treść odpowiedzi
Brak
Przykładowa odpowiedź
Response Status:
HTTP/1.1 202 Accepted
Response Headers:
Last-Modified: <date>
ETag: "0x8CEB669D794AFE2"
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2015-02-21
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>
Autoryzacja
Ta operacja może być wywoływana przez właściciela konta lub przez klienta posiadającego sygnaturę dostępu współdzielonego, która ma uprawnienia do zapisu w pliku docelowym lub jego udziale. Należy pamiętać, że sygnatura dostępu współdzielonego określona w żądaniu ma zastosowanie tylko do pliku docelowego.
Dostęp do pliku źródłowego lub obiektu blob jest autoryzowany oddzielnie, zgodnie z opisem w szczegółach nagłówka x-ms-copy-sourceżądania .
W poniższej tabeli opisano sposób autoryzacji obiektów docelowych i źródłowych dla Copy File operacji:
| File | Autoryzacja z kluczem udostępnionym lub kluczem udostępnionym Lite | Autoryzacja z sygnaturą dostępu współdzielonego | Obiekt publiczny, który nie wymaga autoryzacji |
|---|---|---|---|
| Plik docelowy | Tak | Tak | Nie dotyczy |
| Plik źródłowy na tym samym koncie | Tak | Tak | Nie dotyczy |
| Plik źródłowy na innym koncie | Nie | Tak | Nie dotyczy |
| Źródłowy obiekt blob na tym samym koncie lub innym koncie | Nie | Tak | Tak |
Atrybuty systemu plików
| Atrybut | Atrybut pliku Win32 | Definicja |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
Plik jest tylko do odczytu. Aplikacje mogą odczytywać plik, ale nie mogą go zapisywać ani usuwać. |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
Plik jest ukryty. Nie jest on uwzględniany w zwykłych listach katalogów. |
System |
FILE_ATTRIBUTE_SYSTEM |
System operacyjny używa części pliku lub używa pliku wyłącznie. |
None |
FILE_ATTRIBUTE_NORMAL |
Plik nie ma innych atrybutów ustawionych. Ten atrybut jest prawidłowy tylko wtedy, gdy jest używany samodzielnie. |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
Plik jest plikiem archiwum. Aplikacje zazwyczaj używają tego atrybutu do oznaczania plików do tworzenia kopii zapasowej lub usuwania. |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
Plik jest używany do przechowywania tymczasowego. |
Offline |
FILE_ATTRIBUTE_OFFLINE |
Dane pliku nie są natychmiast dostępne. Ten atrybut systemu plików zapewnia głównie zgodność z systemem Windows. Azure Files nie obsługuje go z opcjami magazynu w trybie offline. |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
Usługa indeksowania zawartości nie zindeksuje pliku. |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
Skaner integralności danych w tle nie odczytuje strumienia danych użytkownika. Ten atrybut systemu plików zapewnia głównie zgodność z systemem Windows. |
Uwagi
Operacja Copy File może zakończyć się asynchronicznie. Możesz użyć identyfikatora kopiowania zwracanego x-ms-copy-id przez nagłówek odpowiedzi, aby sprawdzić stan operacji kopiowania lub anulować ją. Azure Files kopiuje pliki w sposób optymalny.
Jeśli plik docelowy istnieje, zostanie zastąpiony. Nie można zmodyfikować pliku docelowego, gdy operacja kopiowania jest w toku.
Operacja Copy File zawsze kopiuje cały źródłowy obiekt blob lub plik. Kopiowanie zakresu bajtów lub zestawu bloków nie jest obsługiwane.
Źródłem Copy File operacji może być plik, który znajduje się w migawce udziału. Miejsce docelowe Copy File operacji nie może być plikiem, który znajduje się w migawce udziału.
Gdy źródło operacji kopiowania zawiera ETag wartości, jeśli w źródle zostaną wprowadzone jakiekolwiek zmiany, gdy operacja jest w toku, operacja zakończy się niepowodzeniem. Próba zmiany pliku docelowego, gdy operacja kopiowania jest w toku, zakończy się niepowodzeniem z kodem stanu 409 (konflikt).
Wartość ETag pliku docelowego zmienia się po rozpoczęciu Copy File operacji. Nadal zmienia się ona często podczas operacji kopiowania.
Kopiowanie właściwości i metadanych
Podczas kopiowania obiektu blob lub pliku do pliku docelowego są kopiowane następujące właściwości systemowe z tymi samymi wartościami:
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
Plik docelowy jest zawsze taki sam jak źródłowy obiekt blob lub plik. Wartość nagłówka Content-Length pliku docelowego jest zgodna z wartością tego nagłówka źródłowego obiektu blob lub pliku.
Kopiowanie dzierżawionego obiektu blob lub pliku do pliku
Operacja Copy File jest odczytywana tylko z źródłowego obiektu blob lub pliku, więc dzierżawa obiektu źródłowego nie ma wpływu na operację. Operacja Copy File zapisuje ETag wartość źródłowego obiektu blob lub pliku po uruchomieniu operacji.
ETag Jeśli wartość zmieni się przed zakończeniem operacji kopiowania, operacja zakończy się niepowodzeniem. Możesz zapobiec zmianom źródłowego obiektu blob pliku, dzierżawiając go podczas operacji kopiowania.
Jeśli plik docelowy ma aktywną nieskończoną dzierżawę, należy określić jego identyfikator dzierżawy w wywołaniu Copy File operacji. Podczas gdy operacja kopiowania jest oczekująca, każda operacja dzierżawy w pliku docelowym kończy się niepowodzeniem z kodem stanu 409 (Konflikt). Nieskończona dzierżawa pliku docelowego jest zablokowana w ten sposób podczas operacji kopiowania, niezależnie od tego, czy kopiujesz do pliku docelowego, który ma inną nazwę od źródła, czy kopiuje do pliku docelowego, który ma taką samą nazwę jak źródło. Jeśli klient określa identyfikator dzierżawy w pliku, który jeszcze nie istnieje, Azure Files zwraca kod stanu 412 (Warunek wstępny niepowodzenie).
Praca z oczekującą operacją kopiowania
Operacja Copy File może zakończyć kopiowanie plików asynchronicznie. Użyj poniższej tabeli, aby określić następny krok na podstawie kodu stanu, który Copy File zwraca:
| Kod stanu | Znaczenie |
|---|---|
| 202 (Zaakceptowano), x-ms-copy-status: powodzenie | Operacja kopiowania zakończyła się pomyślnie. |
| 202 (Zaakceptowano), x-ms-copy-status: oczekiwanie | Operacja kopiowania nie została zakończona. Sonduj docelowy obiekt blob przy użyciu polecenia , Get File Properties aby sprawdzić x-ms-copy-status , aż operacja kopiowania zakończy się lub zakończy się niepowodzeniem. |
| 4xx, 500 lub 503 | Operacja kopiowania nie powiodła się. |
Podczas operacji i po Copy File operacji właściwości pliku docelowego zawierają identyfikator kopii Copy File operacji i adres URL źródłowego obiektu blob lub pliku. Po zakończeniu operacji Azure Files zapisuje wartość czasu i wyniku (success, failedlub aborted) we właściwościach pliku docelowego. Jeśli operacja ma failed wynik, x-ms-copy-status-description nagłówek zawiera ciąg szczegółów błędu.
Oczekująca Copy File operacja ma limit czasu dwutygodniowego. Próba kopiowania, która nie została zakończona po dwóch tygodniach, i pozostawia pusty plik z x-ms-copy-status polem ustawionym na failed wartość i x-ms-status-description polem ustawionym na 500 (OperationCancelled). Sporadyczne błędy niekrytyczne, które mogą wystąpić podczas operacji kopiowania, mogą utrudniać postęp operacji, ale nie powodują niepowodzenia. W takich przypadkach x-ms-copy-status-description opisano sporadyczne błędy.
Każda próba zmodyfikowania pliku docelowego podczas operacji kopiowania zakończy się niepowodzeniem z kodem stanu 409 (konflikt), "Kopiuj plik w toku".
Jeśli wywołasz operację Abort Copy Filex-ms-copy-status:aborted , zobaczysz nagłówek . Plik docelowy będzie miał nienaruszone metadane i długość pliku o długości 0 bajtów. Możesz powtórzyć oryginalne wywołanie, aby Copy File ponowić próbę wykonania operacji.
Rozliczenia
Konto docelowe Copy File operacji jest obciążane opłatą za jedną transakcję w celu rozpoczęcia operacji. Konto docelowe wiąże się również z jedną transakcją dla każdego żądania anulowania lub żądania stanu operacji kopiowania.
Gdy plik źródłowy lub obiekt blob znajduje się na innym koncie, konto źródłowe generuje koszty transakcji. Ponadto jeśli konta źródłowe i docelowe znajdują się w różnych regionach (na przykład Północno-wschodnie stany USA i Południowe stany USA), przepustowość używana do przeniesienia żądania jest obciążana kontem źródłowym jako ruch wychodzący. Ruch wychodzący między kontami w tym samym regionie jest bezpłatny.