Udostępnij za pośrednictwem

Umieść blok z adresu URL

Operacja Put Block From URL tworzy nowy blok do zatwierdzenia w ramach obiektu blob, w którym zawartość jest odczytywana z adresu URL. Ten interfejs API jest dostępny od wersji 2018-03-28.

Żądanie

Żądanie Put Block From URL można skonstruować w następujący sposób. Zalecamy używanie protokołu HTTPS. Zastąp myaccount nazwą konta magazynu:

Identyfikator URI żądania metody PUT Wersja protokołu HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id Protokół HTTP/1.1

Emulowane żądanie usługi magazynu

Podczas wysyłania żądania względem emulowanej usługi magazynu określ nazwę hosta emulatora i port usługi Blob Service jako 127.0.0.1:10000, a następnie nazwę emulowanego konta magazynu:

Identyfikator URI żądania metody PUT Wersja protokołu HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id Protokół HTTP/1.1

Aby uzyskać więcej informacji, zobacz Use the Azurite emulator for local Azure Storage development (Używanie emulatora Azurite do lokalnego programowania w usłudze Azure Storage).

Parametry identyfikatora URI

Parametr Opis
blockid To jest wymagane. Prawidłowa wartość ciągu Base64, która identyfikuje blok. Przed kodowaniem ciąg musi być mniejszy lub równy 64 bajtom w rozmiarze.

W przypadku określonego obiektu blob długość określonej wartości parametru blockid musi być taka sama dla każdego bloku.

Uwaga: ciąg Base64 musi być zakodowany w adresie URL.
timeout Opcjonalny. Parametr timeout jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi Blob Service.

Nagłówki zapytań

Wymagane i opcjonalne nagłówki żądań zostały opisane w poniższej tabeli:

Nagłówek żądania Opis
Authorization To jest 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 To jest wymagane. Określa uniwersalny czas koordynowany (UTC) dla żądania. 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. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage. W przypadku Put Block From URLprogramu musi to być wersja 2018-03-28 lub nowsza.
Content-Length To jest wymagane. Określa liczbę bajtów przesyłanych w treści żądania. Wartość tego nagłówka musi być ustawiona na 0. Jeśli długość nie jest równa 0, operacja kończy się niepowodzeniem z kodem stanu 400 (nieprawidłowe żądanie).
x-ms-copy-source:name To jest wymagane. Określa adres URL źródłowego obiektu blob. Wartość może być adresem URL o długości do 2 kibibajtów (KiB), który określa obiekt blob. Wartość powinna być zakodowana w adresie URL, tak jak będzie się pojawiać w identyfikatorze URI żądania. Źródłowy obiekt blob musi być publiczny lub autoryzowany za pośrednictwem sygnatury dostępu współdzielonego. Jeśli źródłowy obiekt blob jest publiczny, do wykonania operacji nie jest wymagana autoryzacja. Oto kilka przykładów adresów URL obiektów źródłowych:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Opcjonalny. Określa schemat autoryzacji i podpis dla źródła kopii. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.

Uwaga: W przypadku programu Microsoft Entra obsługiwany jest tylko schemat elementu nośnego.

Uwaga: Jeśli obiekt źródłowy jest publicznie dostępny lub obiekt źródłowy znajduje się na koncie magazynu i używasz tokenu SAS, który jest przekazywany w x-ms-copy-source:nameprogramie , ten nagłówek nie jest potrzebny.

Ten nagłówek jest obsługiwany w wersjach 2020-10-02 i nowszych.
x-ms-source-range Opcjonalny. Przekazuje tylko bajty obiektu blob w źródłowym adresie URL w określonym zakresie. Jeśli ten nagłówek nie zostanie określony, cała zawartość źródłowego obiektu blob zostanie przekazana jako pojedynczy blok. Aby uzyskać więcej informacji, zobacz Określanie nagłówka zakresu dla operacji usługi Blob Service.
x-ms-source-content-md5 Opcjonalny. Skrót MD5 zawartości bloku z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku podczas transportu danych z identyfikatora URI. Po określeniu tego nagłówka usługa magazynu porównuje skrót zawartości, która dotarła ze źródła kopiowania, z tą wartością nagłówka.

Uwaga: Ten skrót MD5 nie jest przechowywany z obiektem blob.

Jeśli dwa skróty nie są zgodne, operacja zakończy się niepowodzeniem z kodem błędu 400 (nieprawidłowe żądanie).
x-ms-source-content-crc64 Opcjonalny. Skrót CRC64 zawartości bloku z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku podczas transportu danych z identyfikatora URI. Po określeniu tego nagłówka usługa magazynu porównuje skrót zawartości, która dotarła ze źródła kopiowania, z tą wartością nagłówka.

Uwaga: Ten skrót CRC64 nie jest przechowywany z obiektem blob.

Jeśli dwa skróty nie są zgodne, operacja zakończy się niepowodzeniem z kodem błędu 400 (nieprawidłowe żądanie).

Jeśli oba x-ms-source-content-md5 nagłówki i x-ms-source-content-crc64 są obecne, żądanie kończy się niepowodzeniem z 400 (nieprawidłowe żądanie).

Ten nagłówek jest obsługiwany w wersjach 2019-02-02 i nowszych.
x-ms-encryption-scope Opcjonalny. Wskazuje zakres szyfrowania, który ma być używany do szyfrowania zawartości źródłowej. Ten nagłówek jest obsługiwany w wersjach 2019-02-02 i nowszych.
x-ms-lease-id:<ID> Wymagane, jeśli blob ma aktywną dzierżawę. Aby wykonać tę operację na obiekcie blob z aktywną dzierżawą, określ prawidłowy identyfikator dzierżawy dla tego nagłówka.
x-ms-client-request-id Opcjonalny. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (KiB), który jest rejestrowany 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 Monitor Azure Blob Storage.
x-ms-file-request-intent Wymagane, jeśli x-ms-copy-source nagłówek jest adresem URL pliku platformy Azure, a x-ms-copy-source-authorization nagłówek określa token OAuth. Akceptowalna wartość to backup. Ten nagłówek określa, że Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action lub Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action należy przyznać, jeśli są one uwzględnione w zasadach RBAC przypisanych do tożsamości autoryzowanej przy użyciu nagłówka x-ms-copy-source-authorization. Dostępne dla wersji 2025-07-05 i nowszych.

Nagłówki żądań (klucze szyfrowania dostarczone przez klienta)

Od wersji 2019-02-02 w żądaniu można określić następujące nagłówki w celu zaszyfrowania obiektu blob przy użyciu klucza dostarczonego przez klienta. Szyfrowanie przy użyciu klucza dostarczonego przez klienta (i odpowiedniego zestawu nagłówków) jest opcjonalne.

Nagłówek żądania Opis
x-ms-encryption-key To jest wymagane. Klucz szyfrowania AES-256 zakodowany w formacie Base64.
x-ms-encryption-key-sha256 To jest wymagane. Skrót SHA256 zakodowany w formacie Base64 klucza szyfrowania.
x-ms-encryption-algorithm: AES256 To jest wymagane. Określa algorytm do użycia na potrzeby szyfrowania. Wartość tego nagłówka musi mieć wartość AES256.

Ciało żądania

Żaden.

Przykładowe żądanie

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2018-03-28  
x-ms-date: Sat, 31 Mar 2018 14:37:35 GMT    
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-499

Odpowiedź

Odpowiedź zawiera kod stanu HTTP i zestaw nagłówków odpowiedzi.

Kod stanu

Pomyślna operacja zwraca kod stanu 201 (Utworzono).

Aby uzyskać więcej informacji na temat kodów stanu, zobacz Stan i kody błędów.

Nagłówki odpowiedzi

Odpowiedź dla tej operacji zawiera następujące nagłówki. Odpowiedź może również zawierać dodatkowe standardowe nagłówki HTTP. Wszystkie standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1 .

Nagłówek odpowiedzi Opis
Content-MD5 Zwrócone w taki sposób, aby klient mógł sprawdzić integralność zawartości komunikatu. Wartość tego nagłówka jest obliczana przez usługę Blob Storage. Nie musi być taka sama jak wartość określona w nagłówkach żądania. W przypadku wersji 2019-02-02 i nowszych ten nagłówek jest zwracany tylko wtedy, gdy żądanie ma ten nagłówek.
x-ms-content-crc64 W przypadku wersji 2019-02-02 i nowszych. Zwrócone w taki sposób, aby klient mógł sprawdzić integralność zawartości komunikatu. Wartość tego nagłówka jest obliczana przez usługę Blob Storage. Nie musi to być takie samo jak wartość określona w nagłówkach żądań.

Zwracane, gdy x-ms-source-content-md5 nagłówek nie jest obecny w żądaniu.
x-ms-request-id Unikatowo identyfikuje żądanie, które zostało wykonane, i można go 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 Wersja usługi Blob Storage, która została użyta do wykonania żądania.
Date Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje godzinę zainicjowania odpowiedzi.
x-ms-request-server-encrypted: true/false Wersja 2015-12-11 i nowsze. Wartość tego nagłówka jest ustawiana na true jeśli zawartość bloku została pomyślnie zaszyfrowana przy użyciu określonego algorytmu. W przeciwnym razie wartość jest ustawiona na wartość false.
x-ms-encryption-key-sha256 Wersja 2019-02-02 lub nowsza. Zwracany, jeśli w żądaniu użyto klucza dostarczonego przez klienta do szyfrowania, dzięki czemu klient może upewnić się, że zawartość żądania została pomyślnie zaszyfrowana przy użyciu podanego klucza.
x-ms-encryption-scope Wersja 2019-02-02 lub nowsza. Zwracane, jeśli w żądaniu użyto zakresu szyfrowania, dzięki czemu klient może upewnić się, że zawartość żądania została pomyślnie zaszyfrowana przy użyciu zakresu szyfrowania.
x-ms-client-request-id Może służyć do rozwiązywania problemów z żądaniami i odpowiadającymi odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka x-ms-client-request-id, jeśli znajduje się w żądaniu, a wartość nie zawiera więcej niż 1024 widocznych znaków ASCII. Jeśli nagłówek x-ms-client-request-id nie znajduje się w żądaniu, nie będzie on obecny w odpowiedzi.

Przykładowa odpowiedź

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sat, 31 Mar 2018 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Autoryzacja

Autoryzacja jest wymagana podczas wywoływania dowolnej operacji dostępu do danych w usłudze Azure Storage. Możesz autoryzować operację Put Block From URL zgodnie z poniższym opisem.

Ważne

Firma Microsoft zaleca używanie identyfikatora Entra firmy Microsoft z tożsamościami zarządzanymi w celu autoryzowania żądań do usługi Azure Storage. Identyfikator Entra firmy Microsoft zapewnia lepsze zabezpieczenia i łatwość użycia w porównaniu z autoryzacją klucza współdzielonego.

Usługa Azure Storage obsługuje używanie identyfikatora Entra firmy Microsoft do autoryzowania żądań do danych obiektów blob. Za pomocą identyfikatora Entra firmy Microsoft możesz użyć kontroli dostępu opartej na rolach (RBAC) platformy Azure, aby udzielić uprawnień podmiotowi zabezpieczeń. Podmiot zabezpieczeń może być użytkownikiem, grupą, jednostką usługi aplikacji lub tożsamością zarządzaną platformy Azure. Podmiot zabezpieczeń jest uwierzytelniany przez Microsoft Entra ID, aby zwrócić token OAuth 2.0. Token może następnie służyć do autoryzowania żądania względem usługi Blob Service.

Aby dowiedzieć się więcej o autoryzacji przy użyciu identyfikatora Entra firmy Microsoft, zobacz Autoryzowanie dostępu do obiektów blob przy użyciu identyfikatora Entra firmy Microsoft.

Uprawnienia

Poniżej wymieniono akcję RBAC niezbędną dla użytkownika microsoft Entra, grupy, tożsamości zarządzanej lub jednostki usługi w celu wywołania operacji Put Block From URL oraz najmniej uprzywilejowanej wbudowanej roli RBAC platformy Azure, która obejmuje tę akcję:

Aby dowiedzieć się więcej na temat przypisywania ról przy użyciu kontroli dostępu opartej na rolach platformy Azure, zobacz Assign an Azure role for access to blob data.

Uwagi

Put Block From URL Przekazuje blok w celu przyszłego dołączenia do blokowego obiektu blob. Blokowy obiekt blob może zawierać maksymalnie 50 000 bloków. Każdy blok może mieć inny rozmiar. Maksymalny rozmiar bloku, który jest przekazywany za pomocą Put Block From URL , to 100 mebibajtów (MiB). Aby przesłać większe bloki (do 4 000 MiB), zobacz Put Block.

W wersji 2020-10-02 lub nowszej autoryzacja firmy Microsoft Entra jest obsługiwana dla źródła operacji kopiowania.

Obiekt blob może mieć maksymalnie 100 000 niezatwierdzonych bloków w dowolnym momencie. Jeśli ta maksymalna wartość zostanie przekroczona, usługa zwróci kod stanu 409 (RequestEntityTooLargeBlockCountExceedsLimit).

W poniższej tabeli opisano maksymalne dozwolone rozmiary bloków i obiektów blob według wersji usługi:

Wersja usługi Maksymalny rozmiar bloku (przez Put Block From URL) Maksymalny rozmiar obiektu blob (za pośrednictwem Put Block List) Maksymalny rozmiar obiektu blob za pośrednictwem pojedynczej operacji zapisu (za pośrednictwem Put Blob From URL)
Wersja 2020-04-08 i nowsze 4 000 MiB Około 190,7 tebibajtów (TiB) (4 000 MiB × 50 000 bloków) 5 000 MiB
Wersje wcześniejsze niż 2020-04-08 100 MiB Około 4,75 TiB (100 MiB × 50 000 bloków) 256 MiB

Po przekazaniu zestawu bloków możesz utworzyć lub zaktualizować obiekt blob na serwerze z tego zestawu, wywołując operację Put Block List . Każdy blok w zestawie jest identyfikowany przez identyfikator bloku, który jest unikatowy w tym obiekcie blob. Identyfikatory bloków są ograniczone do określonego obiektu blob, więc różne obiekty blob mogą mieć bloki o tych samych identyfikatorach.

W przypadku wywołania Put Block From URL obiektu blob, który jeszcze nie istnieje, zostanie utworzony nowy blokowy obiekt blob o długości zawartości 0. Ten obiekt blob jest wyliczany przez List Blobs operację, include=uncommittedblobs jeśli określono opcję. Przekazany blok lub bloki nie są zatwierdzane, dopóki nie wywołasz Put Block List nowego obiektu blob. Utworzony w ten sposób obiekt blob jest utrzymywany na serwerze przez tydzień. Jeśli w tym okresie nie dodano więcej bloków lub zatwierdzonych bloków do obiektu blob, obiekt blob jest wyrzucany jako element bezużyteczny.

Blok, który został pomyślnie przekazany Put Block From URL za pomocą operacji, nie staje się częścią obiektu blob, dopóki nie zostanie zatwierdzony za pomocą Put Block List. Przed Put Block List wywołaniem w celu zatwierdzenia nowego lub zaktualizowanego obiektu blob wszystkie wywołania metody Get Blob zwracają zawartość obiektu blob bez dołączania niezatwierdzonego bloku.

Jeśli przekażesz blok, który ma ten sam identyfikator bloku co inny blok, który nie został jeszcze zatwierdzony, ostatni przekazany blok o tym identyfikatorze zostanie zatwierdzony w następnej pomyślnej Put Block List operacji.

Po Put Block List wywołaniu wszystkie niezatwierdzone bloki określone na liście bloków są zatwierdzane jako część nowego obiektu blob. Wszystkie niezatwierdzone bloki, które nie zostały określone na liście bloków dla obiektu blob, są wyrzucane i usuwane z usługi Blob Storage. Wszystkie niezatwierdzone bloki są również wyrzucane jako elementy bezużyteczne, jeśli w ciągu tygodnia od ostatniej pomyślnej Put Block From URL operacji nie ma żadnych pomyślnych wywołań tego Put Block List samego obiektu blob lub Put Block From URL w tym samym obiekcie blob. Jeśli Put Blob zostanie wywołana w obiekcie blob, wszystkie niezatwierdzone bloki zostaną wyrzucone jako elementy bezużyteczne.

Jeśli obiekt blob ma aktywną dzierżawę, klient musi określić prawidłowy identyfikator dzierżawy w żądaniu, aby zapisać blok w obiekcie blob. Jeśli klient nie określi identyfikatora dzierżawy lub określi nieprawidłowy identyfikator dzierżawy, usługa Blob Storage zwróci kod stanu 412 (Warunek wstępny nie powiódł się). Jeśli klient określi identyfikator dzierżawy, ale obiekt blob nie ma aktywnej dzierżawy, usługa Blob Storage zwraca również kod stanu 412 (Warunek wstępny nie powiódł się).

W przypadku określonego obiektu blob wszystkie identyfikatory bloków muszą mieć tę samą długość. Jeśli blok zostanie przekazany z identyfikatorem bloku o innej długości niż identyfikatory bloków dla wszystkich istniejących niezatwierdzonych bloków, usługa zwraca kod odpowiedzi na błąd 400 (Nieprawidłowe żądanie).

Wywołanie Put Block From URL nie aktualizuje czasu ostatniej modyfikacji istniejącego obiektu blob.

Wywołanie Put Block From URL stronicowego obiektu blob zwraca błąd.

Wywołanie Put Block From URL obiektu blob "archiwum" zwraca błąd, a wywołanie go w hot obiekcie blob or cool nie zmienia warstwy obiektu blob.

Fakturowanie

Żądania cen mogą pochodzić od klientów korzystających z interfejsów API usługi Blob Storage bezpośrednio za pośrednictwem interfejsu API REST usługi Blob Storage lub z biblioteki klienta usługi Azure Storage. Te żądania naliczają opłaty za transakcję. Typ transakcji wpływa na sposób naliczania opłat za konto. Na przykład transakcje odczytu są naliczane do innej kategorii rozliczeniowej niż transakcje zapisu. W poniższej tabeli przedstawiono kategorię rozliczeń dla żądań Put Block From URL na podstawie typu konta magazynu:

Operacja Typ konta magazynowania Kategoria rozliczeń
Umieść blok z adresu URL (konto docelowe1) Obiekt Blob typu Premium
Standard ogólnego przeznaczenia v2
Standardowa wersja do ogólnego użytku 1		 Operacje zapisu
Umieść blok z adresu URL (konto źródłowe2) Obiekt Blob typu Premium
Standard ogólnego przeznaczenia v2
Standardowa wersja do ogólnego użytku 1		 Operacje odczytu

1Konto docelowe jest obciążane opłatą za jedną transakcję w celu zainicjowania zapisu.
cyfra arabskaKonto źródłowe generuje jedną transakcję dla każdego żądania odczytu do obiektu źródłowego.

Ponadto, jeśli konta źródłowe i docelowe znajdują się w różnych regionach (na przykład Północne stany USA i Południowe stany USA), przepustowość używana do transferu żądania jest naliczana na źródłowym koncie magazynu jako ruch wychodzący. Ruch wychodzący między kontami w tym samym regionie jest bezpłatny.

Aby dowiedzieć się więcej o cenach dla określonych kategorii rozliczeń, zobacz Cennik usługi Azure Blob Storage.

Zobacz także