pozyskiwanie do
Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer
Polecenie .ingest into pobiera 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.
Nuta
Ta metoda pozyskiwania jest przeznaczona do eksploracji i tworzenia prototypów. Nie używaj go w scenariuszach produkcyjnych ani dużych ilości.
Nuta
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 Table Ingestor.
Składnia
.ingest [async] intotableNazwa_tabeliSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Dowiedz się więcej na temat konwencji składni .
Parametry
| Nazwa | Typ | Wymagane | Opis |
|---|---|---|---|
async |
string |
Jeśli zostanie określony, polecenie zwraca natychmiast i kontynuuje pozyskiwanie w tle. Wyniki polecenia obejmują OperationId wartość, która może być następnie używana z .show operation polecenia w celu pobrania stanu ukończenia pozyskiwania i wyników. |
|
| |
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 parametrów połączenia magazynu . Pojedyncze parametry połączenia muszą odwoływać się do pojedynczego pliku hostowanego przez konto magazynu. Pozyskiwanie wielu plików można wykonać, określając wiele parametrów połączenia lub pozyskiwania z zapytania tabeli zewnętrznej. |
Nuta
Zalecamy używanie literałów ciągu zaciemnionych dla 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żny
W pozyskiwania w kolejce dane 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łasność | Opis | Przykład |
|---|---|---|
ingestionMapping |
Wartość ciągu wskazująca sposób mapowania danych z pliku źródłowego na rzeczywiste kolumny w tabeli. Zdefiniuj wartość format z odpowiednim typem mapowania. Zobacz mapowania danych. |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")(przestarzałe: avroMapping, csvMapping, jsonMapping) |
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 wartość format z odpowiednim typem mapowania. Zobacz mapowania danych. |
with (format="csv", ingestionMappingReference = "Mapping1")(przestarzałe: avroMappingReference, csvMappingReference, jsonMappingReference) |
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, używana jest 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 upewnij się, że właściwość Lookback w obowiązującej zakresów tabeli docelowej zasad scalania jest zgodna z określoną wartością. |
with (creationTime="2017-02-13") |
extend_schema |
Wartość logiczna, która, jeśli zostanie określona, instruuje polecenie, aby rozszerzyć schemat tabeli (wartość domyślna to false). Ta opcja dotyczy tylko poleceń .append i .set-or-append. Tylko dozwolone rozszerzenia schematu mają więcej kolumn dodanych do tabeli na końcu. |
Jeśli oryginalny schemat tabeli jest (a:string, b:int), prawidłowe rozszerzenie schematu byłoby (a:string, b:int, c:datetime, d:string), ale (a:string, c:datetime) nie byłoby prawidłowe |
folder |
Aby polecenia 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 pozyskiwania według: tagi. |
Właściwości with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') wskazują, że jeśli dane z tagiem ingest-by:Part0001 już istnieją, nie zakoń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 ustawiona na wartość truewskazuje, że pozyskiwanie powinno ignorować pierwszy rekord każdego pliku. Ta właściwość jest przydatna w przypadku plików w CSVi podobnych formatach, jeśli pierwszy rekord w pliku to nazwy kolumn. Domyślnie zakłada się, że 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 polecenia .set-or-replace. 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 ustawiona na truewskazuje, ż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. Aby uzyskać wyjaśnienie różnych opcji, zobacz Pozyskiwanie danych. |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (jest to 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 są ignorowane. | with (zipPattern="*.csv") |
Uwierzytelnianie i autoryzacja
Każde parametry połączenia magazynu wskazują 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 |
|---|---|---|
| personifikacji |
Czytelnik danych obiektu blob usługi Storage | Czytelnik |
| tokenu 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 | ||
| klucza dostępu konta usługi |
Ta metoda uwierzytelniania nie jest obsługiwana w usłudze Gen1. | |
| tożsamości zarządzanej | 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.
| Nazwa | Typ | 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żna go użyć za pomocą polecenia .show operation. |
Nuta
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.
... 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 parametrów tylko dla tajnej części parametrów 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
Poniższy przykład umożliwia pozyskiwanie pojedynczego pliku 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')