Dołączanie bloku z adresu URL

Operacja Append Block From URL zatwierdza nowy blok danych na końcu istniejącego uzupełnionego obiektu blob.

Operacja Append Block From URL jest dozwolona tylko wtedy, gdy obiekt blob został utworzony z ustawioną wartością x-ms-blob-typeAppendBlob. Append Block From URL program jest obsługiwany tylko w wersji 2018-11-09 lub nowszej.

Żądanie

Żądanie można skonstruować Append Block From URL w następujący sposób. Zalecane jest użycie 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=appendblock HTTP/1.1

Podczas wysyłania żądania 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 limitu czasu jest wyrażony w sekundach. Aby uzyskać więcej informacji, zobacz Ustawianie limitów czasu dla operacji usługi 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 usług Azure Storage.
Content-Length Wymagane. Określa liczbę bajtów przesyłanych w treści żądania. Wartość tego nagłówka musi być ustawiona na zero. Jeśli długość nie jest równa zero, operacja zakończy się niepowodzeniem z kodem błędu 400 (nieprawidłowe żądanie).
x-ms-copy-source:name Wymagane. Określa adres URL źródłowego obiektu blob. Wartość może być adresem URL o długości do 2 KiB, który określa obiekt blob. Wartość powinna być zakodowana w adresie URL, tak jak w identyfikatorze URI żądania. Źródłowy obiekt blob musi być publiczny lub musi być 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 kopiowania. Aby uzyskać więcej informacji, zobacz Autoryzowanie żądań do usługi Azure Storage.
Tylko program nośny schematu jest obsługiwany w przypadku Tożsamość Microsoft Entra.
Ten nagłówek jest obsługiwany w wersji 2020-10-02 lub nowszej.
x-ms-source-range Opcjonalny. Przekazuje tylko bajty obiektu blob w źródłowym adresie URL w określonym zakresie. Jeśli nie zostanie określona, cała zawartość źródłowego obiektu blob zostanie przekazana jako pojedynczy blok dołączania. Aby uzyskać więcej informacji, zobacz Określanie nagłówka zakresu dla operacji usługi Blob Storage .
x-ms-source-content-md5 Opcjonalny. Skrót MD5 zawartości bloku dołączania z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku dołączania 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.

Należy pamiętać, że 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-source-content-crc64 Opcjonalny. Skrót CRC64 zawartości bloku dołączania z identyfikatora URI. Ten skrót służy do weryfikowania integralności bloku dołączania 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.

Należy pamiętać, że 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ą zarówno x-ms-source-content-md5 nagłówki, jak i x-ms-source-content-crc64 żądanie kończy się niepowodzeniem z błędem 400 (nieprawidłowe żądanie).

Ten nagłówek jest obsługiwany w wersji 2019-02-02 lub nowszej.
x-ms-encryption-scope Opcjonalny. Wskazuje zakres szyfrowania używany do szyfrowania zawartości źródłowej. Ten nagłówek jest obsługiwany w wersji 2019-02-02 lub nowszej.
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.
x-ms-blob-condition-maxsize Opcjonalny nagłówek warunkowy. Maksymalna długość bajtów dozwolona dla uzupełnialnych obiektów blob. Append Block From URL Jeśli operacja spowoduje przekroczenie tego limitu obiektu 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 wartością 412 (Niepowodzenie warunku wstępnego).
x-ms-blob-condition-appendpos Opcjonalny nagłówek warunkowy, używany tylko dla Append Block from URL operacji. Liczba wskazująca przesunięcie bajtów do porównania. Append Block from URL kończy się powodzeniem tylko wtedy, gdy pozycja dołączania jest równa tej liczbie. Jeśli tak nie jest, żądanie zakończy się niepowodzeniem z błędem 412 (Niepowodzenie warunku wstępnego).

Ta operacja obsługuje użycie dodatkowych, warunkowych nagłówków, aby upewnić się, że interfejs API zakończy się powodzeniem tylko wtedy, gdy zostanie spełniony określony warunek. Aby uzyskać więcej informacji, zobacz Określanie nagłówków warunkowych dla operacji usługi 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 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 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: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
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 używa wartości do wykonywania operacji warunkowych PUT przy użyciu nagłówka If-Match żądania.
Last-Modified Data/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. Usługa Blob Storage oblicza wartość tego nagłówka. 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 wersji 2019-02-02 lub nowszej. Ten nagłówek jest zwracany, aby klient mógł sprawdzić integralność zawartości wiadomości. Usługa Blob Storage oblicza wartość tego nagłówka. Nie musi to być ta sama wartość określona w nagłówkach żądania.

Ten nagłówek jest zwracany, gdy x-ms-source-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 wygenerowana przez usługę, która wskazuje godzinę, o której zainicjowano odpowiedź.
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.

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 From URL zgodnie z poniższym opisem.

Szczegóły autoryzacji w tej sekcji dotyczą miejsca docelowego kopiowania. Aby uzyskać więcej informacji na temat autoryzacji źródła kopii, zobacz szczegóły nagłówka x-ms-copy-sourceżądania .

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 Append Block From URL 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

Append Block From URL 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. Dozwolone jest maksymalnie 50 000 dołączań dla każdego uzupełnialnych obiektów blob, gdzie. 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 From URL) 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)

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

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

Obiekty blob przekazane przy użyciu polecenia Append Block From URL nie uwidaczniają identyfikatorów bloków, więc 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 modułu zapisywania mogą używać tego nagłówka, aby określić, czy Append Block From URL 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 HTTP 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 zwraca kod błędu 412.

Jeśli wywołasz Append Block From URL istniejący blokowy obiekt blob lub stronicowy obiekt blob, usługa zwróci kod błędu 409 (Konflikt). Jeśli wywołasz Append Block From URL obiekt blob nieistniejący, usługa zwróci kod błędu 404 (Nie znaleziono).

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. 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 aplikacje mogą dodawać epoki lub numery sekwencji w dołączanych danych.

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

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 From URL żądań na podstawie typu konta magazynu:

Operacja Typ konta magazynu Kategoria rozliczeń
Dołączanie bloku z adresu URL (konto docelowe1) Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2
Standardowa ogólnego przeznaczenia, wersja 1
Operacje zapisu
Dołączanie bloku z adresu URL (konto źródłowe2) Blokowy obiekt blob w warstwie Premium
Standardowa ogólnego przeznaczenia, wersja 2
Standardowa ogólnego przeznaczenia, wersja 1
Operacje odczytu

1Konto docelowe jest obciążane opłatą za jedną transakcję w celu zainicjowania zapisu.
2Konto źródłowe powoduje naliczenie jednej transakcji dla każdego żądania odczytu do źródła.