Pozyskiwanie z magazynu

  • Artykuł

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 w formacie CSV z 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 funkcji Table Ingestor .

Składnia

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Dowiedz się więcej o konwencjach składniowych.

Parametry

Nazwa Typ Wymagane 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 żadnego obiektu mapowania schematu, używany jest schemat bazy danych w kontekście.
SourceDataLocator string ✔️ Jedna lub rozdzielona przecinkami lista parametrów połączenia magazynu. Pojedynczy parametry połączenia musi odwoływać się do pojedynczego pliku hostowanego przez konto magazynu. Pozyskiwanie wielu plików może odbywać się przez określenie wielu parametrów połączenia lub pozyskiwanie z zapytaniatabeli zewnętrznej.

Uwaga

Zalecamy używanie zaciemnionych literałów ciągu dla elementu SourceDataPointer. Usługa wyczyści poświadczenia w wewnętrznych śladach i komunikatach o błędach.

Właściwości pozyskiwania

Ważne

W poniższej tabeli wymieniono właściwości obsługiwane przez usługę Azure Data Explorer, opisano je i przedstawiono przykłady:

Właściwość 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ść z odpowiednim typem 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ść z odpowiednim typem 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 zostanie określona, zostanie użyta bieżąca wartość (now()). Zastępowanie wartości domyślnej jest przydatne podczas pozyskiwania starszych danych, dzięki czemu zasady przechowywania będą stosowane poprawnie. Po określeniu Lookback upewnij się, że właściwość w obowiązujących zasadach scalania Zakresy tabeli docelowej jest wyrównana do określonej wartości. with (creationTime="2017-02-13")
extend_schema Wartość logiczna, która, jeśli została określona, powoduje, że polecenie rozszerza schemat tabeli (domyślnie na false). Ta opcja dotyczy tylko .append poleceń i ..set-or-append Jedyne dozwolone rozszerzenia schematu mają dodatkowe kolumny dodane 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ąpi 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 pomyślne pozyskiwanie, 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 (na wypadek, gdyby przyszłe pozyskiwanie próbowało ponownie pozyskać te same dane).
ignoreFirstRecord Wartość logiczna, która, jeśli jest ustawiona na truewartość , 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 ponownie utworzyć 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 sformatowana jako ciąg JSON with (tags="['Tag1', 'Tag2']")
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}') (jest to w rzeczywistości zasada domyślna)
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 zostaną zignorowane. with (zipPattern="*.csv")

Uwierzytelnianie i autoryzacja

Każdy 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 przeprowadzenia 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.
Microsoft Entra token dostępu
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.

Nazwa Typ Opis
ExtentId guid Unikatowy identyfikator fragmentu danych wygenerowany przez polecenie .
Element Załadowany string Co najmniej jeden plik magazynu powiązany z tym rekordem.
Czas trwania timespan Jak długo trwało pozyskiwanie danych.
Haserrors bool Niezależnie od tego, czy ten rekord reprezentuje błąd pozyskiwania, czy nie.
Identyfikator operacji guid Unikatowy identyfikator reprezentujący operację. Można użyć polecenia .show operation .

Uwaga

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

Przykłady

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

Poniższy przykład instruuje klaster, aby odczytywał dwa obiekty blob z Azure Blob Storage jako pliki CSV i pozyskiwał ich zawartość do tabeli T. Element ... reprezentuje sygnaturę dostępu współdzielonego usługi Azure Storage, która zapewnia dostęp do odczytu do każdego obiektu blob. Zwróć również uwagę na użycie 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?...'
)

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

W poniższym przykładzie pokazano, jak odczytać plik CSV z 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 Azure Data Lake Storage Gen 2 (ADLSv2). Poświadczenia używane w tym miejscu (...) są poświadczeniami konta magazynu (kluczem udostępnionym) i 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 pozyskuje pojedynczy plik z 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). Pokazano również, jak określić właściwości pozyskiwania.

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

Amazon S3 z kluczem dostępu

Poniższy przykład pozyskuje 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 presigned URL

Poniższy przykład pozyskuje pojedynczy plik z usługi Amazon S3 przy użyciu preSigned URL.

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