Udostępnij za pośrednictwem

Pozyskiwanie z magazynu

  • Artykuł

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer

Polecenie .ingest into pozyskuje dane do tabeli przez "ściąganie" danych z co najmniej jednego pliku magazynu w chmurze. Na przykład polecenie może pobrać 1000 obiektów blob sformatowanych w formacie CSV z usługi Azure Blob Storage, przeanalizować je i pozyskać je razem w jedną tabelę docelową. Dane są dołączane do tabeli bez wpływu na istniejące rekordy i bez modyfikowania schematu tabeli.

Uwaga

Ta metoda pozyskiwania jest przeznaczona do eksploracji i tworzenia prototypów. Nie używaj go w scenariuszach produkcyjnych ani dużych ilości.

Uprawnienia

Aby uruchomić to polecenie, musisz mieć co najmniej uprawnienia ingestor tabeli.

Składnia

.ingest[async] into table TableName SourceDataLocator [with ( IngestionPropertyName = IngestionPropertyValue [, ...] ] )

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko Type Wymagania opis
async string Jeśli zostanie określony, polecenie zwraca natychmiast i kontynuuje pozyskiwanie w tle. Wyniki polecenia zawierają OperationId wartość, która może być następnie używana z poleceniem .show operation w celu pobrania stanu ukończenia pozyskiwania i wyników.
TableName string ✔️ Nazwa tabeli, w której mają być pozyskiwane dane. Nazwa tabeli jest zawsze względna względem bazy danych w kontekście. Jeśli nie podano obiektu mapowania schematu, używany jest schemat bazy danych w kontekście.
SourceDataLocator string ✔️ Pojedyncza lub rozdzielona przecinkami lista parametry połączenia magazynu. Pojedynczy parametry połączenia musi odwoływać się do pojedynczego pliku hostowanego przez konto magazynu. Pozyskiwanie wielu plików można wykonać przez określenie wielu parametry połączenia lub pozyskiwanie z zapytania tabeli zewnętrznej.

Uwaga

Zalecamy używanie zaciemnionych literałów ciągów dla obiektów SourceDataLocators. Usługa będzie usuwać poświadczenia w wewnętrznych śladów i komunikatów o błędach.

Właściwości pozyskiwania

Ważne

Dane pozyskiwania w kolejce są wsadowe przy użyciu właściwości pozyskiwania. Bardziej odrębne właściwości mapowania pozyskiwania, takie jak różne wartości ConstValue, tym bardziej rozdrobnione pozyskiwanie staje się, co może prowadzić do obniżenia wydajności.

W poniższej tabeli wymieniono i opisano obsługiwane właściwości oraz przedstawiono przykłady:

Właściwości opis Przykład
ingestionMapping Wartość ciągu wskazująca sposób mapowania danych z pliku źródłowego na rzeczywiste kolumny w tabeli. Zdefiniuj format wartość za pomocą odpowiedniego typu mapowania. Zobacz mapowania danych. with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(przestarzałe: avroMapping, , jsonMappingcsvMapping)
ingestionMappingReference Wartość ciągu wskazująca sposób mapowania danych z pliku źródłowego na rzeczywiste kolumny w tabeli przy użyciu nazwanego obiektu zasad mapowania. Zdefiniuj format wartość za pomocą odpowiedniego typu mapowania. Zobacz mapowania danych. with (format="csv", ingestionMappingReference = "Mapping1")
(przestarzałe: avroMappingReference, , jsonMappingReferencecsvMappingReference)
creationTime Wartość daty/godziny (sformatowana jako ciąg ISO8601), która ma być używana w czasie tworzenia pozyskanych zakresów danych. Jeśli nie określono, zostanie użyta bieżąca wartość (now()). Zastępowanie wartości domyślnej jest przydatne podczas pozyskiwania starszych danych, dzięki czemu zasady przechowywania są stosowane poprawnie. Po określeniu Lookback upewnij się, że właściwość w obowiązujących zasadach scalania zakresów tabeli docelowej jest zgodna z określoną wartością. with (creationTime="2017-02-13")
extend_schema Wartość logiczna, która, jeśli została określona, instruuje polecenie, aby rozszerzyć schemat tabeli (domyślnie na false). Ta opcja dotyczy tylko .append poleceń i ..set-or-append Tylko dozwolone rozszerzenia schematu mają więcej kolumn dodanych do tabeli na końcu. Jeśli oryginalny schemat tabeli to (a:string, b:int), prawidłowe byłoby rozszerzenie (a:string, b:int, c:datetime, d:string)schematu , ale (a:string, c:datetime) nie byłoby prawidłowe
folder W przypadku poleceń pozyskiwania z zapytania folder do przypisania do tabeli. Jeśli tabela już istnieje, ta właściwość zastępuje folder tabeli. with (folder="Tables/Temporary")
format Format danych (zobacz obsługiwane formaty danych). with (format="csv")
ingestIfNotExists Wartość ciągu, która, jeśli zostanie określona, uniemożliwia pozyskiwanie danych, jeśli tabela zawiera już dane oznaczone tagiem ingest-by: o tej samej wartości. Zapewnia to pozyskiwanie danych idempotentnych. Aby uzyskać więcej informacji, zobacz ingest-by: tags (Pozyskiwanie według tagów). Właściwości with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') wskazują, że jeśli dane z tagiem ingest-by:Part0001 już istnieją, nie ukończ bieżącego pozyskiwania. Jeśli jeszcze nie istnieje, to nowe pozyskiwanie powinno mieć ten zestaw tagów (w przypadku gdy przyszłe pozyskiwanie spróbuje ponownie pozyskać te same dane).
ignoreFirstRecord Wartość logiczna, która, jeśli jest ustawiona na true, wskazuje, że pozyskiwanie powinno ignorować pierwszy rekord każdego pliku. Ta właściwość jest przydatna w przypadku plików w CSVpodobnych formatach, jeśli pierwszy rekord w pliku to nazwy kolumn. Domyślnie przyjmuje się założenie false . with (ignoreFirstRecord=false)
policy_ingestiontime Wartość logiczna, która, jeśli została określona, opisuje, czy włączyć zasady czasu pozyskiwania w tabeli utworzonej przez to polecenie. Wartość domyślna to true. with (policy_ingestiontime=false)
recreate_schema Wartość logiczna, która, jeśli zostanie określona, opisuje, czy polecenie może odtworzyć schemat tabeli. Ta właściwość ma zastosowanie tylko do .set-or-replace polecenia . Ta właściwość ma pierwszeństwo przed właściwością extend_schema , jeśli obie są ustawione. with (recreate_schema=true)
tags Lista tagów do skojarzenia z pozyskanymi danymi sformatowanymi jako ciąg JSON with (tags="['Tag1', 'Tag2']")
TreatGzAsUncompressed Wartość logiczna, która, jeśli jest ustawiona na true, wskazuje, że pliki z rozszerzeniem .gz nie są kompresowane. Ta flaga jest czasami potrzebna podczas pozyskiwania z usługi Amazon AWS S3. with (treatGzAsUncompressed=true)
validationPolicy Ciąg JSON wskazujący, które walidacje mają być uruchamiane podczas pozyskiwania danych reprezentowanych przy użyciu formatu CSV. Zobacz Pozyskiwanie danych, aby uzyskać wyjaśnienie różnych opcji. with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (to są zasady domyślne)
zipPattern Użyj tej właściwości podczas pozyskiwania danych z magazynu, który ma archiwum ZIP. Jest to wartość ciągu wskazująca wyrażenie regularne do użycia podczas wybierania plików w archiwum ZIP do pozyskiwania. Wszystkie inne pliki w archiwum są ignorowane. with (zipPattern="*.csv")

Uwierzytelnianie i autoryzacja

Każda parametry połączenia magazynu wskazuje metodę autoryzacji do użycia w celu uzyskania dostępu do magazynu. W zależności od metody autoryzacji podmiot zabezpieczeń może wymagać udzielenia uprawnień do magazynu zewnętrznego w celu wykonania pozyskiwania.

W poniższej tabeli wymieniono obsługiwane metody uwierzytelniania oraz uprawnienia wymagane do pozyskiwania danych z magazynu zewnętrznego.

Metoda uwierzytelniania Azure Blob Storage / Data Lake Storage Gen2 Data Lake Storage Gen1
Personifikacja Czytelnik danych obiektu BLOB usługi Storage Czytelnik
Token dostępu współdzielonego (SAS) Lista i odczyt Ta metoda uwierzytelniania nie jest obsługiwana w usłudze Gen1.
Token dostępu firmy Microsoft Entra
Klucz dostępu do konta magazynu Ta metoda uwierzytelniania nie jest obsługiwana w usłudze Gen1.
Tożsamość zarządzana Czytelnik danych obiektu BLOB usługi Storage Czytelnik

Zwraca

Wynikiem polecenia jest tabela z dowolną liczbą rekordów, ponieważ istnieją fragmenty danych ("zakresy") generowane przez polecenie . Jeśli żadne fragmenty danych nie zostały wygenerowane, pojedynczy rekord jest zwracany z pustym (zerowym) identyfikatorem zakresu.

Nazwisko Pisz Opis
ExtentId guid Unikatowy identyfikator fragmentu danych wygenerowany przez polecenie .
ItemLoaded string Co najmniej jeden plik magazynu powiązany z tym rekordem.
Czas trwania timespan Jak długo trwało pozyskiwanie danych.
HasErrors bool Czy ten rekord reprezentuje błąd pozyskiwania, czy nie.
Identyfikator operacji guid Unikatowy identyfikator reprezentujący operację. Może być używany z poleceniem .show operation .

Uwaga

To polecenie nie modyfikuje schematu tabeli pozyskiwanej do. W razie potrzeby dane są "konerced" do tego schematu podczas pozyskiwania, a nie odwrotnie (dodatkowe kolumny są ignorowane, a brakujące kolumny są traktowane jako wartości null).

Przykłady

Usługa Azure Blob Storage z sygnaturą dostępu współdzielonego

Poniższy przykład nakazuje bazie danych odczytywanie dwóch obiektów blob z usługi Azure Blob Storage jako plików CSV i pozyskiwanie ich zawartości do tabeli T. Obiekt ... reprezentuje sygnaturę dostępu współdzielonego (SAS) usługi Azure Storage, która zapewnia dostęp do odczytu do każdego obiektu blob. Należy również pamiętać o użyciu zaciemnionych ciągów ( h przed wartościami ciągu), aby upewnić się, że sygnatura dostępu współdzielonego nigdy nie jest rejestrowana.

.ingest into table T (
    h'https://contoso.blob.core.windows.net/container/file1.csv?...',
    h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)

Usługa Azure Blob Storage z tożsamością zarządzaną

W poniższym przykładzie pokazano, jak odczytać plik CSV z usługi Azure Blob Storage i pozyskać jego zawartość do tabeli T przy użyciu uwierzytelniania tożsamości zarządzanej. Aby uzyskać dodatkowe informacje na temat metody uwierzytelniania tożsamości zarządzanej, zobacz Omówienie uwierzytelniania tożsamości zarządzanej.

.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')

Azure Data Lake Storage Gen 2

Poniższy przykład dotyczy pozyskiwania danych z usługi Azure Data Lake Storage Gen 2 (ADLSv2). Poświadczenia używane w tym miejscu (...) to poświadczenia konta magazynu (klucz współużytkowany), a my używamy zaciemnienia ciągu tylko dla tajnej części parametry połączenia.

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)

Azure Data Lake Storage

Poniższy przykład umożliwia pozyskiwanie pojedynczego pliku z usługi Azure Data Lake Storage (ADLS). Używa poświadczeń użytkownika do uzyskiwania dostępu do usługi ADLS (więc nie ma potrzeby traktowania identyfikatora URI magazynu jako zawierającego wpis tajny). Przedstawiono również sposób określania właściwości pozyskiwania.

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')

Usługa Amazon S3 z kluczem dostępu

W poniższym przykładzie pozyskiwany jest pojedynczy plik z usługi Amazon S3 przy użyciu identyfikatora klucza dostępu i klucza dostępu tajnego.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  with (format='csv')

Amazon S3 z wstępnie podpisanym adresem URL

Poniższy przykład pozyskuje pojedynczy plik z usługi Amazon S3 przy użyciu wstępnie podpisanego adresu URL.

.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
  with (format='csv')