Umieść blok

  • Artykuł

Operacja Put Block tworzy nowy blok, który ma zostać zatwierdzony w ramach obiektu blob.

Żądanie

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

IDENTYFIKATOR URI żądania PUT Wersja PROTOKOŁU HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

Żądanie usługi magazynu emulowanego

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 PUT Wersja PROTOKOŁU HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id 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 Wymagane. Prawidłowa wartość ciągu Base64, która identyfikuje blok. Przed zakodowaniem ciąg musi być mniejszy lub równy 64 bajtom rozmiaru.

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

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

Nagłówki żądań

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

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. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji usług Azure Storage.
Content-Length Wymagane. Długość zawartości bloku w bajtach. Blok musi być mniejszy lub równy 4000 mebibajtów (MiB) w rozmiarze wersji 2019-12-12 lub nowszej. Zobacz sekcję Uwagi, aby zapoznać się z limitami w starszych wersjach.

Jeśli długość nie zostanie podana, operacja kończy się niepowodzeniem z kodem stanu 411 (Wymagana długość).
Content-MD5 Opcjonalny. Skrót MD5 zawartości bloku. Ten skrót służy do weryfikowania integralności bloku podczas transportu. Po określeniu tego nagłówka usługa magazynu porównuje skrót zawartości, która dotarła do tej wartości nagłówka.

Uwaga: ten skrót MD5 nie jest przechowywany w obiekcie blob.

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

Uwaga: ten skrót CRC64 nie jest przechowywany w obiekcie blob.

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

Jeśli istnieją nagłówki Content-MD5 i x-ms-content-crc64, żądanie kończy się niepowodzeniem z błędem 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 używany do szyfrowania zawartości żądania. Ten nagłówek jest obsługiwany w wersjach 2019-02-02 i nowszych.
x-ms-lease-id:<ID> Wymagane, jeśli obiekt 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. Udostępnia 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 Monitorowanie Azure Blob Storage.

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

Od wersji 2019-02-02 można określić następujące nagłówki na żądanie szyfrowania 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 Wymagane. Klucz szyfrowania AES-256 zakodowany w formacie Base64.
x-ms-encryption-key-sha256 Wymagane. Skrót SHA256 zakodowany w formacie Base64 klucza szyfrowania.
x-ms-encryption-algorithm: AES256 Wymagane. Określa algorytm do użycia do szyfrowania. Wartość tego nagłówka musi mieć wartość AES256.

Treść żądania

Treść żądania zawiera zawartość bloku.

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: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576

Reakcja

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

Kod stanu

Operacja zakończona powodzeniem zwraca kod stanu 201 (utworzono).

Aby uzyskać informacje o kodach stanu, zobacz Kody stanu i błędów.

Nagłówki odpowiedzi

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

Nagłówek odpowiedzi Opis
Content-MD5 Zwrócono, aby klient mógł sprawdzić integralność zawartości komunikatu. Wartość tego nagłówka jest obliczana przez usługę Blob Storage i niekoniecznie jest to ta sama 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 ten nagłówek jest zwracany, aby klient mógł sprawdzić integralność zawartości komunikatu. Wartość tego nagłówka jest obliczana przez usługę Blob Storage i nie musi być tą samą wartością określoną w nagłówkach żądania.

Ten nagłówek jest zwracany, gdy 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 Wskazuje wersję usługi Blob Storage użytą do wykonania żądania. Ten nagłówek jest zwracany w przypadku żądań, które zostały wykonane w wersji 2009-09-19 lub nowszej.
Date Wartość daty/godziny UTC wygenerowana przez usługę, która wskazuje, kiedy została zainicjowana odpowiedź.
x-ms-request-server-encrypted: true/false Wersja 2015-12-11 lub nowsza. Wartość tego nagłówka jest ustawiana na true wartość , jeśli zawartość żądania zostanie pomyślnie zaszyfrowana przy użyciu określonego algorytmu. W przeciwnym razie wartość jest ustawiona na false.
x-ms-encryption-key-sha256 Wersja 2019-02-02 lub nowsza. Ten nagłówek jest zwracany, jeśli żądanie użyło klucza dostarczonego przez klienta do szyfrowania, aby klient mógł 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. Ten nagłówek jest zwracany, jeśli żądanie używa 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 im odpowiedziami. Wartość tego nagłówka jest równa wartości x-ms-client-request-id nagłówka, jeśli jest obecna w żądaniu, a wartość zawiera nie więcej niż 1024 widoczne znaki ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, nie jest obecny w odpowiedzi.

Przykładowa odpowiedź

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 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 zgodnie z poniższym opisem.

Usługa Azure Storage obsługuje autoryzację żądań do danych obiektów blob przy użyciu Tożsamość Microsoft Entra. Dzięki Tożsamość Microsoft Entra 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 Tożsamość Microsoft Entra w celu zwrócenia tokenu 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 na temat autoryzacji przy użyciu Tożsamość Microsoft Entra, zobacz Autoryzowanie dostępu do obiektów blob przy użyciu Tożsamość Microsoft Entra.

Uprawnienia

Poniżej przedstawiono akcję RBAC niezbędną do wywołania Put Block operacji przez użytkownika, grupę lub jednostkę usługi Microsoft Entra oraz najmniej uprzywilejowaną wbudowaną rolę RBAC platformy Azure obejmującą tę akcję:

Aby dowiedzieć się więcej na temat przypisywania ról przy użyciu kontroli dostępu opartej na rolach platformy Azure, zobacz Przypisywanie roli platformy Azure w celu uzyskania dostępu do danych obiektów blob.

Uwagi

Put Block przekazuje blok do przyszłego włączenia do blokowego obiektu blob. Każdy blok w blokowym obiekcie blob może mieć inny rozmiar. Blokowy obiekt blob może zawierać maksymalnie 50 000 zatwierdzonych bloków.

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 (za pośrednictwem Put Block) Maksymalny rozmiar obiektu blob (za pośrednictwem Put Block List) Maksymalny rozmiar obiektu blob za pośrednictwem operacji pojedynczego zapisu (za pośrednictwem Put Blobmetody )
Wersja 2019-12-12 lub nowsza 4000 MiB Około 190,7 tebibajtów (TiB) (4000 MiB × 50 000 bloków) 5000 MiB
Wersje 2016-05-31 do 2019-07-07 100 MiB Około 4,75 TiB (100 MiB × 50 000 bloków) 256 MiB
Wersje starsze niż 2016-05-31 4 MiB Około 195 gibibajtów (GiB) (4 MiB × 50 000 bloków) 64 MiB

Maksymalna liczba niezatwierdzonych bloków, które mogą być skojarzone z obiektem blob, wynosi 100 000. Jeśli ta liczba zostanie przekroczona, usługa zwróci kod stanu 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Po przekazaniu zestawu bloków można utworzyć lub zaktualizować obiekt blob na serwerze z tego zestawu, wywołując operację Umieść listę bloków . Każdy blok w zestawie jest identyfikowany przez identyfikator bloku, który jest unikatowy w ramach tego obiektu blob. Identyfikatory bloków są ograniczone do określonego obiektu blob, więc różne obiekty blob mogą mieć bloki z tymi samymi identyfikatorami.

Jeśli wywołasz Put Block obiekt blob, który jeszcze nie istnieje, zostanie utworzony nowy blokowy obiekt blob o długości 0. Ten obiekt blob jest wyliczany przez operację List Blobs , jeśli include=uncommittedblobs określono opcję. Blok lub bloki przekazywane nie zostaną zatwierdzone do momentu wywołania Put Block List nowego obiektu blob. Utworzony w ten sposób obiekt blob jest utrzymywany na serwerze przez tydzień. Jeśli w tym czasie nie dodano więcej bloków ani zatwierdzonych bloków do obiektu blob, obiekt blob jest zbierany w pamięci.

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

Jeśli przekażesz blok o tym samym identyfikatorze bloku co inny blok, który nie został jeszcze zatwierdzony, ostatni przekazany blok o tym identyfikatorze zostanie zatwierdzony podczas 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 w ramach nowego obiektu blob. Wszystkie niezatwierdzone bloki, które nie zostały określone na liście bloków dla obiektu blob, są usuwane i usuwane z usługi Blob Storage. Wszystkie niezatwierdzone bloki są również wyrzucane na śmieci, jeśli nie ma żadnych pomyślnych wywołań do Put Block lub Put Block List na tym samym obiekcie blob w ciągu tygodnia po ostatniej pomyślnej Put Block operacji. Jeśli obiekt Blob Put jest wywoływany w obiekcie blob, wszystkie niezatwierdzone bloki są zbierane w pamięci.

Jeśli obiekt blob ma aktywną dzierżawę, klient musi określić prawidłowy identyfikator dzierżawy żądania, aby zapisać blok w obiekcie blob. Jeśli klient nie określi identyfikatora dzierżawy lub określa nieprawidłowy identyfikator dzierżawy, usługa Blob Storage zwraca kod stanu 412 (Warunek wstępny nie powiodło się). Jeśli klient określa 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 powiodło się).

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

Jeśli próbujesz przekazać blok większy niż 4000 miB dla wersji 2019-12-12 lub nowszej, większy niż 100 MiB w wersji 2016-05-31 lub nowszej lub większej niż 4 MiB dla starszych wersji, usługa zwraca kod stanu 413 (Jednostka żądania zbyt duża). Usługa zwraca również dodatkowe informacje o błędzie w odpowiedzi, w tym maksymalny dozwolony rozmiar bloku w bajtach.

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

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

Wywołanie Put Block zarchiwizowanego obiektu blob zwraca błąd i wywoływanie go w hot obiekcie blob lub cool nie zmienia warstwy obiektu blob.

Rozliczenia

Żądania cenowe 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 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 Put Block żądań na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Umieść blok Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2
Standardowa ogólnego przeznaczenia, wersja 1		 Operacje zapisu

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

Zobacz też

Autoryzowanie żądań do usługi Azure Storage
Kody stanu i błędów
Kody błędów usługi Blob Service
Ustawianie limitów czasu dla operacji usługi Blob Service