Wykonywanie zapytań dotyczących danych w usłudze Azure Synapse Analytics

Artykuł
11/07/2024

Dostęp do usługi Azure Synapse z usługi Azure Databricks można uzyskać przy użyciu łącznika usługi Azure Synapse, który używa COPY instrukcji w usłudze Azure Synapse do wydajnego transferu dużych ilości danych między klastrem usługi Azure Databricks i wystąpieniem usługi Azure Synapse przy użyciu konta magazynu usługi Azure Data Lake Storage Gen2 na potrzeby tymczasowego przemieszczania.

Ważne

Konfiguracje opisane w tym artykule są eksperymentalne. Funkcje eksperymentalne są udostępniane zgodnie z oczekiwaniami i nie są obsługiwane przez usługę Databricks za pośrednictwem pomocy technicznej klienta. Aby uzyskać pełną obsługę federacji zapytań, należy zamiast tego użyć usługi Lakehouse Federation, która umożliwia użytkownikom usługi Azure Databricks korzystanie ze składni wykazu aparatu Unity i narzędzi do zapewniania ładu danych.

Usługa Azure Synapse Analytics to oparty na chmurze magazyn danych przedsiębiorstwa, który wykorzystuje masowe przetwarzanie równoległe (MPP) do szybkiego uruchamiania złożonych zapytań w petabajtach danych.

Ważne

Ten łącznik jest używany tylko z wystąpieniami dedykowanej puli usługi Synapse i nie jest zgodny z innymi składnikami usługi Synapse.

Uwaga

COPY jest dostępny tylko w wystąpieniach usługi Azure Data Lake Storage Gen2. Jeśli szukasz szczegółowych informacji na temat pracy z programem Polybase, zobacz Connecting Azure Databricks and Azure Synapse with PolyBase (legacy) (Łączenie usług Azure Databricks i Azure Synapse z technologią PolyBase (starsza wersja).

Przykładowa składnia usługi Synapse

Zapytania dotyczące usługi Synapse można wykonywać w języku Scala, Python, SQL i R. W poniższych przykładach kodu są używane klucze konta magazynu i przekazywanie poświadczeń magazynu z usługi Azure Databricks do usługi Synapse.

Uwaga

Użyj parametry połączenia udostępnionej przez witrynę Azure Portal, która umożliwia szyfrowanie Secure Sockets Layer (SSL) dla wszystkich danych wysyłanych między sterownikiem Spark a wystąpieniem usługi Azure Synapse za pośrednictwem połączenia JDBC. Aby sprawdzić, czy szyfrowanie SSL jest włączone, możesz wyszukać encrypt=true w parametry połączenia.

Ważne

Lokalizacje zewnętrzne zdefiniowane w wykazie aparatu Unity nie są obsługiwane jako tempDir lokalizacje.

Scala


// Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
val df: DataFrame = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") /* Optional - will use default port 1433 if not specified. */
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") /* If schemaName not provided, default to "dbo". */
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .load()

// Load data from an Azure Synapse query.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("query", "select x, count(*) as cnt from table group by x")
  .load()

// Apply some transformations to the data, then use the
// Data Source API to write the data back to another table in Azure Synapse.

df.write
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .save()

Python


# Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
df = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") # Optional - will use default port 1433 if not specified.
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") # If schemaName not provided, default to "dbo".
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .load()

# Load data from an Azure Synapse query.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("query", "select x, count(*) as cnt from table group by x") \
  .load()

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

df.write \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .save()

SQL


-- Set up the storage account access key in the notebook session conf.
SET fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net=<your-storage-account-access-key>;

-- Read data using SQL. The following example applies to Databricks Runtime 11.3 LTS and above.
CREATE TABLE example_table_in_spark_read
USING sqldw
OPTIONS (
  host '<hostname>',
  port '<port>' /* Optional - will use default port 1433 if not specified. */
  user '<username>',
  password '<password>',
  database '<database-name>'
  dbtable '<schema-name>.<table-name>', /* If schemaName not provided, default to "dbo". */
  forwardSparkAzureStorageCredentials 'true',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Read data using SQL. The following example applies to Databricks Runtime 10.4 LTS and below.
CREATE TABLE example_table_in_spark_read
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbtable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Write data using SQL.
-- Create a new table, throwing an error if a table with the same name already exists:

CREATE TABLE example_table_in_spark_write
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbTable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
)
AS SELECT * FROM table_to_save_in_spark;

R

# Load SparkR
library(SparkR)

# Set up the storage account access key in the notebook session conf.
conf <- sparkR.callJMethod(sparkR.session(), "conf")
sparkR.callJMethod(conf, "set", "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net", "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   dbTable = "<your-table-name>",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Load data from an Azure Synapse query.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   query = "select x, count(*) as cnt from table group by x",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

write.df(
  df,
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  forward_spark_azure_storage_credentials = "true",
  dbTable = "<your-table-name>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

Jak działa uwierzytelnianie między usługą Azure Databricks i usługą Synapse?

Łącznik usługi Azure Synapse używa trzech typów połączeń sieciowych:

Sterownik platformy Spark do usługi Azure Synapse
Klaster Spark na konto usługi Azure Storage
Usługa Azure Synapse do konta usługi Azure Storage

Konfigurowanie dostępu do usługi Azure Storage

Zarówno usługi Azure Databricks, jak i Synapse wymagają uprzywilejowanego dostępu do konta usługi Azure Storage, które ma być używane na potrzeby tymczasowego magazynu danych.

Usługa Azure Synapse nie obsługuje używania sygnatury dostępu współdzielonego na potrzeby dostępu do konta magazynu. Dostęp dla obu usług można skonfigurować, wykonując jedną z następujących czynności:

Użyj klucza konta i wpisu tajnego dla konta magazynu i ustaw wartość forwardSparkAzureStorageCredentials true. Zobacz Ustawianie właściwości platformy Spark w celu skonfigurowania poświadczeń platformy Azure w celu uzyskania dostępu do usługi Azure Storage.
Użyj usługi Azure Data Lake Storage Gen2 z uwierzytelnianiem OAuth 2.0 i ustaw wartość enableServicePrincipalAuth true. Zobacz Konfigurowanie połączenia z usługi Azure Databricks do usługi Synapse przy użyciu protokołu OAuth 2.0 z jednostką usługi.
Skonfiguruj wystąpienie usługi Azure Synapse tak, aby miało tożsamość usługi zarządzanej i ustaw wartość useAzureMSI .true

Wymagane uprawnienia usługi Azure Synapse

Ponieważ używa COPY go w tle, łącznik usługi Azure Synapse wymaga od użytkownika połączenia JDBC uprawnienia do uruchamiania następujących poleceń w połączonym wystąpieniu usługi Azure Synapse:

COPY INTO

Jeśli tabela docelowa nie istnieje w usłudze Azure Synapse, oprócz powyższego polecenia wymagane jest uprawnienie do uruchomienia następującego polecenia:

CREATE TABLE

Poniższa tabela zawiera podsumowanie uprawnień wymaganych do zapisu za pomocą COPYpolecenia :

Uprawnienia (wstawianie do istniejącej tabeli)	Uprawnienia (wstawianie do nowej tabeli)
ADMINISTER DATABASE BULK OPERATIONS (ADMINISTROWANIE ZBIORCZYMI OPERACJAMI BAZY DANYCH) INSERT	ADMINISTER DATABASE BULK OPERATIONS (ADMINISTROWANIE ZBIORCZYMI OPERACJAMI BAZY DANYCH) INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

Konfiguracje sieci

Jeśli skonfigurujesz zaporę w usłudze Azure Synapse, musisz skonfigurować ustawienia sieci, aby umożliwić usłudze Azure Databricks dotarcie do usługi Azure Synapse. Najpierw upewnij się, że obszar roboczy usługi Azure Databricks został wdrożony we własnej sieci wirtualnej, a następnie wdróż usługę Azure Databricks w sieci wirtualnej platformy Azure (iniekcja sieci wirtualnej).Najpierw upewnij się, że obszar roboczy usługi Azure Databricks jest wdrożony we własnej sieci wirtualnej. Następnie można skonfigurować reguły zapory ip w usłudze Azure Synpase, aby zezwolić na połączenia z podsieci do konta usługi Synapse. Zobacz Reguły zapory adresów IP usługi Azure Synapse Analytics.

Konfigurowanie połączenia z usługi Azure Databricks do usługi Synapse przy użyciu protokołu OAuth 2.0 z jednostką usługi

Możesz uwierzytelnić się w usłudze Azure Synapse Analytics przy użyciu jednostki usługi z dostępem do bazowego konta magazynu. Aby uzyskać więcej informacji na temat używania poświadczeń jednostki usługi na potrzeby dostępu do konta usługi Azure Storage, zobacz temat Połączenie do usługi Azure Data Lake Storage Gen2 lub usługi Blob Storage. Należy ustawić enableServicePrincipalAuth opcję na true w konfiguracji połączenia Azure Databricks Synapse connector options reference (Opcje łącznika usługi Synapse usługi Azure Databricks), aby umożliwić łącznikowi uwierzytelnianie za pomocą jednostki usługi.

Opcjonalnie możesz użyć innej jednostki usługi dla połączenia usługi Azure Synapse Analytics. Poniższy przykład umożliwia skonfigurowanie poświadczeń jednostki usługi dla konta magazynu i opcjonalnych poświadczeń jednostki usługi dla usługi Synapse:

ini

; Defining the Service Principal credentials for the Azure storage account
fs.azure.account.auth.type OAuth
fs.azure.account.oauth.provider.type org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider
fs.azure.account.oauth2.client.id <application-id>
fs.azure.account.oauth2.client.secret <service-credential>
fs.azure.account.oauth2.client.endpoint https://login.microsoftonline.com/<directory-id>/oauth2/token

; Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.databricks.sqldw.jdbc.service.principal.client.id <application-id>
spark.databricks.sqldw.jdbc.service.principal.client.secret <service-credential>

Scala

// Defining the Service Principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

// Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Python

# Defining the service principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

# Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

R

# Load SparkR
library(SparkR)
conf <- sparkR.callJMethod(sparkR.session(), "conf")

# Defining the service principal credentials for the Azure storage account
sparkR.callJMethod(conf, "set", "fs.azure.account.auth.type", "OAuth")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.secret", "<service-credential>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

# Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Obsługiwane tryby zapisywania dla zapisów wsadowych

Łącznik usługi Azure Synapse obsługuje ErrorIfExiststryby , Ignore, Appendi Overwrite zapisywania z domyślnym trybem to ErrorIfExists. Aby uzyskać więcej informacji na temat obsługiwanych trybów zapisywania na platformie Apache Spark, zobacz dokumentację spark SQL dotyczącą trybów zapisywania.

Dokumentacja opcji łącznika usługi Synapse usługi Azure Databricks

Dostępne OPTIONS w usłudze Spark SQL obsługują następujące ustawienia:

Parametr	Wymagania	Wartość domyślna	Uwagi
`dbTable`	Tak, chyba że `query` określono	Brak wartości domyślnej	Tabela do utworzenia lub odczytania w usłudze Azure Synapse. Ten parametr jest wymagany podczas zapisywania danych z powrotem do usługi Azure Synapse. Możesz również użyć `{SCHEMA NAME}.{TABLE NAME}` polecenia , aby uzyskać dostęp do tabeli w danym schemacie. Jeśli nie podano nazwy schematu, zostanie użyty domyślny schemat skojarzony z użytkownikiem JDBC. Wcześniej obsługiwany `dbtable` wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case".
`query`	Tak, chyba że `dbTable` określono	Brak wartości domyślnej	Zapytanie do odczytu w usłudze Azure Synapse. W przypadku tabel określonych w zapytaniu można również `{SCHEMA NAME}.{TABLE NAME}` uzyskać dostęp do tabeli w danym schemacie. Jeśli nie podano nazwy schematu, zostanie użyty domyślny schemat skojarzony z użytkownikiem JDBC.
`user`	Nie.	Brak wartości domyślnej	Nazwa użytkownika usługi Azure Synapse. Należy używać razem z opcją `password` . Można go używać tylko wtedy, gdy użytkownik i hasło nie zostaną przekazane w adresie URL. Przekazanie obu spowoduje wystąpienie błędu.
`password`	Nie.	Brak wartości domyślnej	Hasło usługi Azure Synapse. Należy używać razem z opcją `user` . Można go używać tylko wtedy, gdy użytkownik i hasło nie zostaną przekazane w adresie URL. Przekazanie obu spowoduje wystąpienie błędu.
`url`	Tak	Brak wartości domyślnej	Adres URL JDBC z `sqlserver` ustawionym jako podprotocol. Zaleca się używanie parametry połączenia udostępnianych przez witrynę Azure Portal. Ustawienie `encrypt=true` jest zdecydowanie zalecane, ponieważ umożliwia szyfrowanie SSL połączenia JDBC. Jeśli `user` i `password` są ustawione oddzielnie, nie musisz ich uwzględniać w adresie URL.
`jdbcDriver`	Nie.	Określony przez podprotocol adresu URL JDBC	Nazwa klasy sterownika JDBC do użycia. Ta klasa musi znajdować się na ścieżce klasy. W większości przypadków nie należy określać tej opcji, ponieważ odpowiednia nazwa klasy sterownika powinna być automatycznie określana przez podprotocol adresu URL JDBC. Wcześniej obsługiwany `jdbc_driver` wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case".
`tempDir`	Tak	Brak wartości domyślnej	Identyfikator `abfss` URI. Zalecamy użycie dedykowanego kontenera usługi Blob Storage dla usługi Azure Synapse. Wcześniej obsługiwany `tempdir` wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case". Nie można użyć lokalizacji zewnętrznej zdefiniowanej w wykazie aparatu Unity jako `tempDir` lokalizacji.
`tempCompression`	Nie.	`SNAPPY`	Algorytm kompresji, który ma być używany do kodowania/dekodowania tymczasowego zarówno przez platformę Spark, jak i usługę Azure Synapse. Obecnie obsługiwane wartości to: `UNCOMPRESSED`, `SNAPPY` i `GZIP`.
`forwardSparkAzureStorageCredentials`	Nie.	fałsz	Jeśli `true`biblioteka automatycznie odnajduje poświadczenia klucza dostępu konta magazynu używane przez platformę Spark do nawiązywania połączenia z kontenerem usługi Blob Storage i przekazuje te poświadczenia do usługi Azure Synapse za pośrednictwem protokołu JDBC. Te poświadczenia są wysyłane w ramach zapytania JDBC. Dlatego zdecydowanie zaleca się włączenie szyfrowania SSL połączenia JDBC podczas korzystania z tej opcji. Podczas konfigurowania uwierzytelniania magazynu należy ustawić dokładnie jedną z wartości `useAzureMSI` i `forwardSparkAzureStorageCredentials` na `true`. Alternatywnie można ustawić `enableServicePrincipalAuth` wartość i `true` użyć jednostki usługi dla uwierzytelniania JDBC i magazynu. Opcja `forwardSparkAzureStorageCredentials` nie obsługuje uwierzytelniania w magazynie przy użyciu tożsamości usługi zarządzanej lub jednostki usługi. Obsługiwany jest tylko klucz dostępu do konta magazynu. Wcześniej obsługiwany `forward_spark_azure_storage_credentials` wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case".
`useAzureMSI`	Nie.	fałsz	Jeśli `true`biblioteka określi `IDENTITY = 'Managed Service Identity'` i nie `SECRET` dla tworzonych przez nią poświadczeń o określonym zakresie bazy danych. Podczas konfigurowania uwierzytelniania magazynu należy ustawić dokładnie jedną z wartości `useAzureMSI` i `forwardSparkAzureStorageCredentials` na `true`. Alternatywnie można ustawić `enableServicePrincipalAuth` wartość i `true` użyć jednostki usługi dla uwierzytelniania JDBC i magazynu.
`enableServicePrincipalAuth`	Nie.	fałsz	Jeśli `true`biblioteka użyje podanych poświadczeń jednostki usługi, aby nawiązać połączenie z kontem usługi Azure Storage i usługą Azure Synapse Analytics za pośrednictwem protokołu JDBC. Jeśli wartość lub `forward_spark_azure_storage_credentials` `useAzureMSI` jest ustawiona na `true`wartość , ta opcja będzie miała pierwszeństwo przed jednostką usługi w uwierzytelnianiu magazynu.
`tableOptions`	Nie.	`CLUSTERED COLUMNSTORE INDEX`, `DISTRIBUTION = ROUND_ROBIN`	Ciąg służący do określania opcji tabeli podczas tworzenia tabeli usługi Azure Synapse ustawionej za pomocą polecenia `dbTable`. Ten ciąg jest przekazywany dosłownie do `WITH` klauzuli instrukcji SQL wydanej `CREATE TABLE` dla usługi Azure Synapse. Wcześniej obsługiwany `table_options` wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case".
`preActions`	Nie.	Brak wartości domyślnej (pusty ciąg)	Oddzielona `;` lista poleceń SQL do wykonania w usłudze Azure Synapse przed zapisaniem danych w wystąpieniu usługi Azure Synapse. Te polecenia SQL muszą być prawidłowymi poleceniami akceptowanymi przez usługę Azure Synapse. Jeśli którykolwiek z tych poleceń zakończy się niepowodzeniem, jest traktowany jako błąd, a operacja zapisu nie jest wykonywana.
`postActions`	Nie.	Brak wartości domyślnej (pusty ciąg)	`;` Oddzielona lista poleceń SQL do wykonania w usłudze Azure Synapse po pomyślnym zapisaniu danych przez łącznik w wystąpieniu usługi Azure Synapse. Te polecenia SQL muszą być prawidłowymi poleceniami akceptowanymi przez usługę Azure Synapse. Jeśli którykolwiek z tych poleceń zakończy się niepowodzeniem, zostanie on potraktowany jako błąd i otrzymasz wyjątek po pomyślnym zapisaniu danych w wystąpieniu usługi Azure Synapse.
`maxStrLength`	Nie.	256	`StringType` na platformie Spark jest mapowany na `NVARCHAR(maxStrLength)` typ w usłudze Azure Synapse. Możesz użyć `maxStrLength` polecenia , aby ustawić długość ciągu dla wszystkich `NVARCHAR(maxStrLength)` kolumn typu, które znajdują się w tabeli o nazwie `dbTable` w usłudze Azure Synapse. Wcześniej obsługiwany `maxstrlength` wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case".
`applicationName`	Nie.	`Databricks-User-Query`	Tag połączenia dla każdego zapytania. Jeśli nie zostanie określona lub wartość jest pustym ciągiem, domyślnie dodawany jest adres URL JDBC. Wartość domyślna uniemożliwia narzędziu do monitorowania usługi Azure DB zgłaszanie fałszywych alertów iniekcji SQL względem zapytań.
`maxbinlength`	Nie.	Brak wartości domyślnej	Steruj długością `BinaryType` kolumn. Ten parametr jest tłumaczony jako `VARBINARY(maxbinlength)`.
`identityInsert`	Nie.	fałsz	Ustawienie w celu `true` włączenia `IDENTITY_INSERT` trybu, który wstawia wartość ramki danych podaną w kolumnie tożsamości tabeli usługi Azure Synapse. Zobacz Jawne wstawianie wartości do kolumny IDENTITY.
`externalDataSource`	Nie.	Brak wartości domyślnej	Wstępnie aprowizowane zewnętrzne źródło danych do odczytu danych z usługi Azure Synapse. Zewnętrzne źródło danych może być używane tylko z technologią PolyBase i usuwa wymaganie uprawnień CONTROL, ponieważ łącznik nie musi tworzyć poświadczeń o określonym zakresie i zewnętrznego źródła danych w celu załadowania danych. Na przykład użycie i lista uprawnień wymaganych podczas korzystania z zewnętrznego źródła danych można znaleźć w temacie Required Azure Synapse permissions for PolyBase with the external data source option (Wymagane uprawnienia usługi Azure Synapse dla programu PolyBase z opcją zewnętrznego źródła danych).
`maxErrors`	Nie.	0	Maksymalna liczba wierszy, które można odrzucić podczas operacji odczytu i zapisu przed anulowaniem operacji ładowania. Odrzucone wiersze zostaną zignorowane. Jeśli na przykład dwa z dziesięciu rekordów zawierają błędy, zostaną przetworzone tylko osiem rekordów. Zobacz dokumentację REJECT_VALUE w artykule CREATE EXTERNAL TABLE and MAXERRORS documentation in COPY (TWORZENIE TABELI ZEWNĘTRZNEj i FUNKCJI MAXERRORS w artykule COPY).
`inferTimestampNTZType`	Nie.	fałsz	Jeśli `true`wartości typu Azure Synapse `TIMESTAMP` są interpretowane jako `TimestampNTZType` (sygnatura czasowa bez strefy czasowej) podczas operacji odczytu. W przeciwnym razie wszystkie znaczniki czasu są interpretowane jako `TimestampType` niezależnie od typu w bazowej tabeli usługi Azure Synapse.

Uwaga

tableOptions, , preActionspostActionsi maxStrLength są istotne tylko podczas zapisywania danych z usługi Azure Databricks do nowej tabeli w usłudze Azure Synapse.
Mimo że wszystkie nazwy opcji źródła danych są bez uwzględniania wielkości liter, zalecamy określenie ich w przypadku "camel case" w celu uzyskania jasności.

Wypychanie zapytań do usługi Azure Synapse

Łącznik usługi Azure Synapse implementuje zestaw reguł optymalizacji, aby wypchnąć następujące operatory do usługi Azure Synapse:

Filter
Project
Limit

Operatory Project i Filter obsługują następujące wyrażenia:

Większość operatorów logicznych
Porównania
Podstawowe operacje arytmetyczne
Rzutowanie liczbowe i ciągowe

Limit W przypadku operatora wypychanie jest obsługiwane tylko wtedy, gdy nie określono kolejności. Na przykład:

SELECT TOP(10) * FROM table, ale nie SELECT TOP(10) * FROM table ORDER BY col.

Uwaga

Łącznik usługi Azure Synapse nie wypycha wyrażeń działających na ciągach, datach lub znacznikach czasu.

Wypychanie zapytań utworzone za pomocą łącznika usługi Azure Synapse jest domyślnie włączone. Można ją wyłączyć, ustawiając wartość spark.databricks.sqldw.pushdown false.

Tymczasowe zarządzanie danymi

Łącznik usługi Azure Synapse nie usuwa plików tymczasowych tworzonych w kontenerze usługi Azure Storage. Usługa Databricks zaleca okresowe usuwanie plików tymczasowych w lokalizacji dostarczonej tempDir przez użytkownika.

Aby ułatwić oczyszczanie danych, łącznik usługi Azure Synapse nie przechowuje plików danych bezpośrednio w obszarze tempDir, ale zamiast tego tworzy podkatalog formularza: <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Można skonfigurować zadania okresowe (przy użyciu funkcji zadań usługi Azure Databricks lub w inny sposób), aby rekursywnie usuwać wszystkie podkatalogi starsze niż określony próg (na przykład 2 dni), przy założeniu, że nie będzie zadań platformy Spark uruchomionych dłużej niż ten próg.

Prostszą alternatywą jest okresowe usunięcie całego kontenera i utworzenie nowego o tej samej nazwie. Wymaga to użycia dedykowanego kontenera dla danych tymczasowych utworzonych przez łącznik usługi Azure Synapse i że można znaleźć przedział czasu, w którym można zagwarantować, że żadne zapytania z udziałem łącznika nie są uruchomione.

Tymczasowe zarządzanie obiektami

Łącznik usługi Azure Synapse automatyzuje transfer danych między klastrem usługi Azure Databricks i wystąpieniem usługi Azure Synapse. W celu odczytywania danych z tabeli usługi Azure Synapse lub wykonywania zapytań lub zapisywania danych w tabeli usługi Azure Synapse łącznik usługi Azure Synapse tworzy obiekty tymczasowe, w tym DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMATi EXTERNAL TABLE w tle. Te obiekty są aktywne tylko przez cały czas trwania odpowiedniego zadania platformy Spark i są automatycznie porzucane.

Jeśli klaster uruchamia zapytanie przy użyciu łącznika usługi Azure Synapse, jeśli proces sterownika spark ulegnie awarii lub zostanie wymuszono ponownie uruchomiony lub jeśli klaster zostanie wymuszono zakończony lub ponownie uruchomiony, obiekty tymczasowe mogą nie zostać usunięte. Aby ułatwić identyfikację i ręczne usuwanie tych obiektów, łącznik usługi Azure Synapse prefiksuje nazwy wszystkich pośrednich obiektów tymczasowych utworzonych w wystąpieniu usługi Azure Synapse z tagiem formularza: tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

Zalecamy okresowe wyszukiwanie ujawnionych obiektów przy użyciu zapytań, takich jak:

SELECT * FROM sys.database_scoped_credentials WHERE name LIKE 'tmp_databricks_%'
SELECT * FROM sys.external_data_sources WHERE name LIKE 'tmp_databricks_%'
SELECT * FROM sys.external_file_formats WHERE name LIKE 'tmp_databricks_%'
SELECT * FROM sys.external_tables WHERE name LIKE 'tmp_databricks_%'

Udostępnij za pośrednictwem

Wykonywanie zapytań dotyczących danych w usłudze Azure Synapse Analytics

Przykładowa składnia usługi Synapse

Scala

Python

SQL

R

Jak działa uwierzytelnianie między usługą Azure Databricks i usługą Synapse?

Konfigurowanie dostępu do usługi Azure Storage

Wymagane uprawnienia usługi Azure Synapse

Konfiguracje sieci

Konfigurowanie połączenia z usługi Azure Databricks do usługi Synapse przy użyciu protokołu OAuth 2.0 z jednostką usługi

ini

Scala

Python

R

Obsługiwane tryby zapisywania dla zapisów wsadowych

Dokumentacja opcji łącznika usługi Synapse usługi Azure Databricks

Wypychanie zapytań do usługi Azure Synapse

Tymczasowe zarządzanie danymi

Tymczasowe zarządzanie obiektami

Opinia

Dodatkowe zasoby