Udostępnij za pośrednictwem

Blok dołączania

  • Artykuł

Operacja Append Block zatwierdza nowy blok danych na końcu istniejącego uzupełnialnych obiektów blob.

Operacja Append Block jest dozwolona tylko wtedy, gdy obiekt blob został utworzony z ustawioną wartością x-ms-blob-typeAppendBlob. Append Block Program jest obsługiwany tylko w wersji 2015-02-21 lub nowszej.

Żądanie

Żądanie można skonstruować Append Block w następujący sposób. Zalecane jest użycie protokołu HTTPS. Zastąp wartość myaccount nazwą konta magazynu.

Identyfikator URI żądania PUT Wersja PROTOKOŁU HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1

Gdy wysyłasz żądanie względem emulowanej usługi magazynu, określ nazwę hosta emulatora i Azure Blob Storage port 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=appendblock 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
timeout Opcjonalny. Parametr jest wyrażony timeout w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji Azure Blob Storage.

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. Aby uzyskać więcej informacji, zobacz Przechowywanie wersji dla usług Azure Storage.
Content-Length Wymagane. Długość zawartości bloku w bajtach. Rozmiar bloku musi być mniejszy lub równy 100 MiB (wersja zapoznawcza) w wersji 2022-11-02 lub nowszej. Zobacz sekcję Uwagi, aby uzyskać limity w starszych wersjach.

Jeśli długość nie zostanie podana, operacja zakoń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 z tą wartością nagłówka.

Pamiętaj, że ten skrót MD5 nie jest przechowywany w obiekcie blob.

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

Pamiętaj, że ten skrót CRC64 nie jest przechowywany w obiekcie blob.

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

Jeśli istnieją nagłówki Content-MD5 i , x-ms-content-crc64 żądanie zakończy się niepowodzeniem z kodem błędu 400.

Ten nagłówek jest obsługiwany w wersjach 2019-02-02 lub 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 lub 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. Zapewnia nieprzezroczystą wartość wygenerowaną przez klienta z limitem znaków 1-kibibyte (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-blob-condition-maxsize Opcjonalny nagłówek warunkowy. Określa maksymalną długość bajtów dozwoloną dla uzupełnialnych obiektów blob. Append Block Jeśli operacja spowoduje przekroczenie tego limitu przez obiekt blob lub jeśli rozmiar obiektu blob jest już większy niż wartość określona w tym nagłówku, żądanie kończy się niepowodzeniem z kodem błędu 412 (Niepowodzenie warunku wstępnego).
x-ms-blob-condition-appendpos Opcjonalny nagłówek warunkowy używany tylko dla Append Block operacji. Liczba wskazuje przesunięcie bajtów do porównania. Append Block kończy się powodzeniem tylko wtedy, gdy pozycja dołączania jest równa tej liczbie. Jeśli tak nie jest, żądanie kończy się niepowodzeniem z kodem błędu 412 (Niepowodzenie warunku wstępnego).

Ta operacja obsługuje użycie dodatkowych nagłówków warunkowych, aby upewnić się, że interfejs API zakończy się pomyślnie tylko wtedy, gdy określony warunek zostanie spełniony. Aby uzyskać więcej informacji, zobacz Określanie nagłówków warunkowych dla operacji Azure Blob Storage.

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

Począwszy od wersji 2019-02-02, można określić następujące nagłówki w żądaniu szyfrowania obiektu blob przy użyciu klucza dostarczonego przez klienta. Szyfrowanie przy użyciu klucza dostarczonego przez klienta (i odpowiadającego mu 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 na potrzeby 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=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"

Reakcja

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

Kod stanu

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

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 standardowe nagłówki są zgodne ze specyfikacją protokołu HTTP/1.1.

Nagłówek odpowiedzi Opis
ETag Element ETag zawiera wartość w cudzysłowie. Klient może użyć wartości do wykonywania operacji warunkowych PUT przy użyciu nagłówka If-Match żądania.
Last-Modified Data i godzina ostatniej modyfikacji obiektu blob. Format daty jest zgodny z dokumentem RFC 1123. Aby uzyskać więcej informacji, zobacz Reprezentacja wartości daty i godziny w nagłówkach.

Każda operacja zapisu obiektu blob (w tym aktualizacje metadanych lub właściwości obiektu blob) zmienia czas ostatniej modyfikacji obiektu blob.
Content-MD5 Ten nagłówek jest zwracany, aby klient mógł sprawdzić integralność zawartości wiadomości. Wartość tego nagłówka jest obliczana przez usługę Blob Storage. Nie musi to być ta sama wartość określona w nagłówkach żądania. W przypadku wersji 2019-02-02 lub nowszej ten nagłówek jest zwracany tylko wtedy, gdy żądanie ma ten nagłówek.
x-ms-content-crc64 W przypadku wersji 2019-02-02 lub nowszej ten nagłówek jest zwracany, aby klient mógł sprawdzić integralność zawartości wiadomości. Wartość tego nagłówka jest obliczana przez usługę Blob Storage. Nie musi to być ta sama wartość określona w nagłówkach żądania.

Ten nagłówek jest zwracany, gdy Content-md5 nagłówek nie jest obecny w żądaniu.
x-ms-request-id Ten nagłówek jednoznacznie identyfikuje wykonane żądanie i może służyć do rozwiązywania problemów z żądaniem.
x-ms-version Wskazuje wersję usługi Blob Storage używaną do uruchomienia żądania. Ten nagłówek jest zwracany w przypadku żądań wysyłanych w wersji 2009-09-19 lub nowszej.
Date Wartość daty/godziny UTC wskazująca godzinę, o której zainicjowano odpowiedź. Usługa generuje tę wartość.
x-ms-blob-append-offset Ten nagłówek odpowiedzi jest zwracany tylko w przypadku operacji dołączania. Zwraca przesunięcie, przy którym blok został zatwierdzony w bajtach.
x-ms-blob-committed-block-count Liczba zatwierdzonych bloków znajdujących się w obiekcie blob. Służy to do kontrolowania liczby dołączań, które można wykonać.
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. Klient może następnie 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. Klient może następnie upewnić się, że zawartość żądania została pomyślnie zaszyfrowana przy użyciu zakresu szyfrowania.
x-ms-client-request-id Ten nagłówek służy do rozwiązywania problemów z żądaniami i odpowiadającymi im odpowiedziami. Wartość tego nagłówka jest równa wartości nagłówka x-ms-client-request-id , jeśli jest obecna w żądaniu. Wartość jest najwyżej 1024 widocznymi znakami ASCII. x-ms-client-request-id Jeśli nagłówek nie znajduje się w żądaniu, ten nagłówek 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: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000

Autoryzacja

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

Ważne

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

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ą dla użytkownika Microsoft Entra, grupy, tożsamości zarządzanej lub jednostki usługi w celu wywołania Append Block operacji 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 Przypisywanie roli platformy Azure w celu uzyskania dostępu do danych obiektów blob.

Uwagi

Append Block przekazuje blok na końcu istniejącego uzupełnialnych obiektów blob. Blok danych jest natychmiast dostępny po pomyślnym wywołaniu na serwerze. Dla każdego uzupełnialnych obiektów blob dozwolonych jest maksymalnie 50 000 dołączanych. Każdy blok może mieć inny rozmiar.

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 Append Block) Maksymalny rozmiar obiektu blob
Wersja 2022-11-02 lub nowsza 100 MiB (wersja zapoznawcza) Około 4,75 TiB (100 MiB × 50 000 bloków)
Wersje starsze niż 2022-11-02 4 MiB Około 195 gibibajtów (GiB) (4 MiB × 50 000 bloków)

Append Block kończy się powodzeniem tylko wtedy, gdy obiekt blob już istnieje.

Obiekty blob przekazane przy użyciu polecenia Append Block nie uwidaczniają identyfikatorów bloków. Nie można wywołać funkcji Pobierz listę bloków względem uzupełnialnych obiektów blob. Spowoduje to wystąpienie błędu.

W żądaniu można określić następujące opcjonalne nagłówki warunkowe:

  • x-ms-blob-condition-appendpos: Ten nagłówek można ustawić na przesunięcie bajtów, przy którym klient oczekuje dołączenia bloku. Żądanie powiedzie się tylko wtedy, gdy bieżące przesunięcie pasuje do określonego przez klienta. W przeciwnym razie żądanie kończy się niepowodzeniem z kodem błędu 412 (Niepowodzenie warunku wstępnego).

    Klienci korzystający z pojedynczego składnika zapisywania mogą używać tego nagłówka do określenia, czy Append Block operacja zakończyła się pomyślnie, pomimo awarii sieci.

  • x-ms-blob-condition-maxsize: Klienci mogą używać tego nagłówka, aby upewnić się, że operacje dołączania nie zwiększają rozmiaru obiektu blob poza oczekiwany maksymalny rozmiar w bajtach. Jeśli warunek zakończy się niepowodzeniem, żądanie zakończy się niepowodzeniem z kodem błędu 412 (Niepowodzenie warunku wstępnego).

Jeśli spróbujesz przekazać blok większy niż dozwolony rozmiar, usługa zwróci kod błędu 413 (Zbyt duża jednostka żądania). Usługa zwraca również dodatkowe informacje o błędzie w odpowiedzi, w tym maksymalny rozmiar bloku dozwolony w bajtach. Jeśli spróbujesz przekazać więcej niż 50 000 bloków, usługa zwróci kod błędu 409 (Konflikt).

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 zwraca kod błędu 412 (Niepowodzenie warunku wstępnego). Jeśli klient określa identyfikator dzierżawy, ale obiekt blob nie ma aktywnej dzierżawy, usługa Blob Storage zwraca również kod błędu 412.

Jeśli wywołasz Append Block istniejący blokowy obiekt blob lub stronicowy obiekt blob, usługa zwróci błąd powodujący konflikt. Jeśli wywołasz Append Block obiekt blob nieistniejący, usługa zwróci również błąd.

Unikaj zduplikowanych lub opóźnionych dołączań

W jednym scenariuszu zapisywania klient może uniknąć zduplikowanych dołączań lub opóźnionych zapisów przy użyciu *x-ms-blob-condition-appendpos nagłówka warunkowego w celu sprawdzenia bieżącego przesunięcia. Klient może również uniknąć duplikatów lub opóźnień, sprawdzając ETag warunkowo przy użyciu polecenia If-Match.

W scenariuszu z wieloma składnikami zapisywania każdy klient może używać nagłówków warunkowych, ale może to nie być optymalne dla wydajności. W przypadku największej przepływności dołączania współbieżnego aplikacje powinny obsługiwać nadmiarowe dołączania i opóźnione dołączania w warstwie aplikacji. Na przykład aplikacja może dodawać epoki lub numery sekwencji w dołączanych danych.

Rozliczenia

Żą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 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 w innej kategorii rozliczeniowej niż transakcje zapisu. W poniższej tabeli przedstawiono kategorię rozliczeń dla Append Block żądań na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Blok dołączania Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2
Standardowa ogólnego przeznaczenia, wersja 1		 Operacje zapisu

Bloki dołączania nie obsługują warstw na poziomie obiektu, ale wywnioskują ich warstwę dostępu z domyślnego ustawienia warstwy dostępu konta i są odpowiednio rozliczane. Aby dowiedzieć się więcej o domyślnym ustawieniu warstwy konta, zobacz Warstwy dostępu dla danych obiektów blob — Azure Storage.

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