Pozyskiwanie z magazynu
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.
Uwaga
Ta metoda pozyskiwania jest przeznaczona do eksploracji i tworzenia prototypów. Nie używaj go w scenariuszach produkcyjnych ani dużych ilości. Aby uzyskać więcej informacji na temat opcji pozyskiwania, zobacz Omówienie pozyskiwania danych.
Uprawnienia
Aby uruchomić to polecenie, musisz mieć co najmniej uprawnienia ingestor tabeli.
Składnia
.ingest[async] intotableTableNameSourceDataLocator [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, , csvMappingjsonMapping) |
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, , csvMappingReferencejsonMappingReference) |
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 nie wygenerowano fragmentów danych, pojedynczy rekord jest zwracany z pustym (zero-wartościowym) identyfikatorem zakresu.
| Nazwisko | Type | 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 |
Niezależnie od tego, czy ten rekord reprezentuje błąd pozyskiwania. |
| 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. Zaciemnione ciągi (h przed wartościami ciągu) są używane do zapewnienia, ż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. Uwierzytelnianie używa identyfikatora tożsamości zarządzanej (identyfikatora obiektu) przypisanego do usługi Azure Blob Storage na platformie Azure. Aby uzyskać więcej informacji, zobacz Tworzenie tożsamości zarządzanej dla kontenerów magazynu.
.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')