Ładuj dane do swojego magazynu za pomocą interfejsu API BCP (wersja zapoznawcza)

Dotyczy:✅ Magazyn w systemie Microsoft Fabric

Interfejs API BCP zapewnia bezpośrednią ścieżkę ładowania danych po stronie klienta, umożliwiając ich załadowanie do Warehouse bez etapowego zapisywania plików w zewnętrznej pamięci masowej.

Important

Ta funkcja jest dostępna w wersji zapoznawczej.

Narzędzie BCP (narzędzie bcp), klasa .NET SqlBulkCopy i klasa Java SQLServerBulkCopy to sprawdzone metody pozyskiwania danych używane w obciążeniach SQL Server, Azure SQL i dedykowanej puli SQL usługi Azure Synapse. Te interfejsy korzystają z interfejsu API BCP i protokołu ładowania zbiorczego TDS, który jest zazwyczaj bardziej wydajny niż instrukcje INSERT wykonywane wiersz po wierszu przy importowaniu dużych ilości danych.

Important

Aby uzyskać najwyższą przepustowość ładowania danych w środowisku produkcyjnym, gdy można najpierw umieścić pliki w obszarze przejściowym, użyj polecenia COPY INTO.

Użyj interfejsu API BCP, gdy dane znajdują się już w warstwie klienckiej lub aplikacyjnej i potrzebujesz bezpośredniego ładowania do tabel hurtowni danych przez połączenie SQL.

Kiedy należy używać interfejsu API BCP

Użyj interfejsu API BCP dla scenariuszy pozyskiwania bezpośredniego, takich jak:

  • Usługi aplikacyjne, które przechowują dane w pamięci i zapisują je partiami.
  • Skrypty operacyjne i runbooki, które ładują pliki za pomocą automatyzacji z poziomu wiersza polecenia.
  • Narzędzia do integracji danych korzystające z semantyki kopiowania zbiorczego SQL.
  • Istniejące narzędzia klienckie lub integracje, które już korzystają z semantyki API BCP i których nie można przekształcić we wzorzec etapowy COPY INTO.
  • Obciążenia związane z mikropartiowaniem, w których klienci przesyłają częste małe partie danych bezpośrednio przez połączenie SQL hurtowni danych.

Prerequisites

  • Użyj uwierzytelniania Microsoft Entra ID. Uwierzytelnianie SQL (nazwa użytkownika i hasło) nie jest obsługiwane w magazynie.

Opcja 1. Używanie bcp.exe do pozyskiwania opartego na skryptach

Użyj narzędzia bcp, jeśli potrzebujesz powtarzalnego ładowania z wiersza polecenia ze skryptów, zaplanowanych zadań lub runbooków. Ta opcja dobrze sprawdza się w przypadku importów z plików, gdy chcesz mieć pełną kontrolę nad ogranicznikami, kodowaniem, wielkością partii i komunikatami o błędach.

Ta opcja jest również zalecana, gdy pliki źródłowe zostały utworzone na podstawie bcp ... out SQL Server, Azure SQL lub podobnych punktów końcowych SQL i chcesz zachować zgodne konwencje plików kopiowania zbiorczego.

Typowy przepływ:

  1. Przygotuj tabelę docelową w magazynie.
  2. Przygotuj plik źródłowy (na przykład CSV) z kolejnością kolumn zgodną z obiektem docelowym lub użyj pliku formatu.
  3. Uruchom bcp ... in, używając parametrów połączenia SQL i bazy danych hurtowni.
  4. Dostosuj opcje, takie jak rozmiar partii i ograniczniki na podstawie rozmiaru i formatu pliku.

Example:

bcp dbo.Sales in sales.csv -S <workspace-endpoint> -d <database> -G -U <user@domain.com> -c -t ,

Przydatne opcje z dokumentacji narzędzia bcp:

  • -SUstawia parametr połączenia z magazynem.
  • -d ustawia docelową bazę danych.
  • -G używa uwierzytelniania Microsoft Entra. Jest to jedyna obsługiwana opcja uwierzytelniania dla tego scenariusza w wersji zapoznawczej.
  • -Uokreśla nazwę główną użytkownika Microsoft Entra dla wzorców logowania interakcyjnego.
  • -c używa formatu danych znaków.
  • -t ustawia terminator pola (, w tym przykładzie).
  • -b może ustawić rozmiar partii dla dużych obciążeń.

Aby uzyskać pełną składnię i opcje właściwe dla poszczególnych platform, zobacz temat Kopiowanie zbiorcze przy użyciu narzędzia bcp.

Opcja 2. Korzystanie z języka C# SqlBulkCopy

Użyj Microsoft. Data.SqlClient.SqlBulkCopy dla usług .NET i aplikacji, które już przechowują dane w pamięci (na przykład DataTable lub DbDataReader). SqlBulkCopy efektywnie przesyła wiersze do tabeli docelowej za pośrednictwem jednego połączenia SQL. Jest to lepszy wybór niż wydawanie wielu indywidualnych INSERT oświadczeń.

Typowy przepływ:

  1. Otwórz połączenie SQL, korzystając z parametrów połączenia magazynu i uwierzytelniania Microsoft Entra.
  2. Utwórz instancję SqlBulkCopy i ustaw DestinationTableName.
  3. (Opcjonalnie) Dodaj mapowania kolumn, jeśli nazwy kolumn źródłowych i docelowych lub kolejność różnią się.
  4. Ustaw właściwości związane z wydajnością, takie jak BatchSize i BulkCopyTimeout.
  5. Wywołaj WriteToServer lub WriteToServerAsync, aby załadować partię.

Example:

using Microsoft.Data.SqlClient;

using var connection = new SqlConnection(connectionString);
await connection.OpenAsync();

using var bulk = new SqlBulkCopy(connection);
bulk.DestinationTableName = "dbo.Sales";
await bulk.WriteToServerAsync(dataTable);

Typowe opcje dostrajania obejmują BatchSize, BulkCopyTimeout oraz jawne mapowania kolumn, gdy schematy źródłowy i docelowy się różnią.

Opcja 3. Używanie narzędzia Java SQLServerBulkCopy

Użyj narzędzia SQLServerBulkCopy w usługach Java, które pozyskiwają dane ze źródeł JDBC lub strumieni danych w pamięci. Zapewnia ona zachowanie ładowania zbiorczego podobne do bcp.exe, ale bezpośrednio w kodzie aplikacji.

Typowy przepływ:

  1. Otwórz połączenie JDBC, używając uwierzytelniania Microsoft Entra i parametrów połączenia z magazynem .
  2. Utwórz instancję SQLServerBulkCopy i ustaw setDestinationTableName.
  3. (Opcjonalnie) Skonfiguruj SQLServerBulkCopyOptions i mapowania kolumn.
  4. Podaj dane źródłowe jako ResultSet, RowSetlub ISQLServerBulkRecord.
  5. Wywołaj writeToServer, aby zaimportować dane.

Example:

try (SQLServerBulkCopy bulkCopy = new SQLServerBulkCopy(connectionString)) {
    bulkCopy.setDestinationTableName("dbo.Sales");
    bulkCopy.writeToServer(resultSet);
}

Interfejs JDBC Bulk Copy API obsługuje zapisywanie danych ze źródeł ResultSet, RowSet i ISQLServerBulkRecord.

Uwagi dotyczące obsługi opcji kopiowania zbiorczego

W tej sekcji wyjaśniono, jak działają typowe opcje kopiowania zbiorczego w Fabric Data Warehouse. Nazwy opcji odpowiadają ustawieniom w środowiskach .NET SqlBulkCopyOptions, Java SQLServerBulkCopyOptions i powiązanym wskazówkom ładowania zbiorczego bcp.

Nie dotyczy opcji

Typowe interfejsy API klienta akceptują następujące opcje, ale kopiowanie zbiorcze w Fabric Data Warehouse ignoruje je i używa domyślnego zachowania usługi:

  • CheckConstraints
  • TableLock
  • KeepNulls
  • FireTriggers

Zagadnienia dotyczące wydajności

Wydajność kopiowania zbiorczego zależy w dużym stopniu od rozmiaru partii i jakości sieci przekazywania przez klienta.

Rozmiar partii

Rozmiar partii ma duży wpływ na przepływność. Każda partia ma stałe obciążenie związane z przetwarzaniem, dlatego wysyłanie bardzo małych partii (na przykład dziesiątki lub setki wierszy) może znacznie zmniejszyć wydajność podczas ładowania dużych zestawów danych.

W przypadku większych obciążeń użyj większych partii. Praktycznym celem jest około 150 MB do 1 GB na partię.

Dobrym punktem wyjścia dla wielu obciążeń jest od 250 MB do 500 MB na partię, a następnie dostosowywanie na podstawie przepływności i limitów pamięci klienta.

Jakość połączenia klienta podczas wysyłania

Kopiowanie zbiorcze przesyła dane strumieniowo z klienta do punktu końcowego hurtowni danych. Jeśli przepustowość wysyłania jest ograniczona lub opóźnienia sieciowe są duże, przepustowość ładowania danych może się zmniejszyć, nawet gdy zasoby hurtowni danych są dostępne.

Aby uzyskać najlepszą wydajność, uruchom aplikację kliencką w tym samym regionie Azure co magazyn i użyj ścieżki sieciowej o wysokiej przepustowości i małych opóźnieniach.

Interfejs API BCP w porównaniu z COPY INTO

  • Użyj interfejsu API BCP , gdy dane są generowane lub przechowywane w warstwie klienta/aplikacji, a pozyskiwanie bezpośrednie jest wymagane.
  • Użyj COPY INTO, jeśli możesz umieścić pliki w magazynie i chcesz użyć podstawowej ścieżki po stronie serwera, aby uzyskać pozyskiwanie danych o najwyższej przepustowości.

Treści powiązane

  • Last updated on