Azure Synapse

Azure Synapse コネクタを使用すると、Azure Synapse SQL プールに接続し、SQL を使用して Azure Synapse データを取得して更新できます。

始める前に

Azure Synapse コネクタを使用する前に、次の作業を行います。

Google Cloud プロジェクトで次の操作を行います。
- コネクタを構成するユーザーに roles/connectors.admin IAM ロールを付与します。
- コネクタに使用するサービスアカウントに、次の IAM ロールを付与します。
  - roles/secretmanager.viewer
  - roles/secretmanager.secretAccessor
  サービスアカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスするのに認証を受ける必要がある人間以外のユーザーを表します。サービスアカウントがない場合は、サービスアカウントを作成する必要があります。詳細については、サービスアカウントを作成するをご覧ください。
- 次のサービスを有効にします。
  - secretmanager.googleapis.com（Secret Manager API）
  - connectors.googleapis.com（Connectors API）
  サービスを有効にする方法については、サービスを有効にするをご覧ください。
以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

コネクタを構成する

コネクタを構成するには、データソース（バックエンドシステム）への接続を作成する必要があります。接続はデータソースに特有です。つまり、多数のデータソースがある場合は、データソースごとに別々の接続を作成する必要があります。接続を作成する手順は次のとおりです。

Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。
[接続] ページに移動
[+ 新規作成] をクリックして [接続の作成] ページを開きます。
[ロケーション] セクションで、接続のロケーションを選択します。
1. リージョン: プルダウンリストからロケーションを選択します
  コネクタをサポートしているリージョンは次のとおりです。
  サポートされているすべてのリージョンの一覧については、ロケーションをご覧ください。
2. [次へ] をクリックします。
[接続の詳細] セクションで、次の操作を行います。
1. コネクタ: 使用可能なコネクタのプルダウンリストから [Azure Synapse] を選択します。
2. コネクタのバージョン: 使用可能なバージョンのプルダウンリストからコネクタのバージョンを選択します。
3. [接続名] フィールドに、接続インスタンスの名前を入力します。
  接続名は次の条件を満たす必要があります。
  - 接続名には英字、数字、ハイフンを使用できます。
  - 文字は小文字のみを使用できます。
  - 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
  - 接続名は 49 文字以内で指定してください。
4. 必要に応じて、接続インスタンスの [説明] を入力します。
5. サービスアカウント: 必要なロールを持つサービスアカウントを選択します。
6. 必要に応じて、接続ノードの設定を構成します。
  - ノードの最小数: 接続ノードの最小数を入力します。
  - ノードの最大数: 接続ノードの最大数を入力します。
  ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。
7. Azure テナント: このプロパティは、データへのアクセスに使用される Microsoft Azure テナントを指定します。
8. データベース: このプロパティは、サーバーレス SQL プールまたは専用 SQL プール内の Synapse データベースの名前を指定します。
9. [送信先] に、次のプロパティを入力します。
10. 必要に応じて、SSL の次のプロパティを入力します。
  - SSL を有効にする: このチェックボックスプロパティで、SSL を有効にするかどうかを指定します。
  - トラストストア: このプロパティでトラストストアを指定します。ラジオボタンを選択して、[Pubic]、[プライベート接続]、[安全でない接続] からトラストストアを選択できます。
  - カスタムトラストストア: このプロパティは、PEM 形式のカスタムトラストストアを含むシークレットを選択するために使用されます。
  - SSL クライアント証明書: このプロパティには、SSL クライアント証明書を指定します。
  - SSL クライアント秘密鍵: このプロパティには、PEM 形式の SSL クライアント秘密鍵を指定します。
  - SSL クライアント証明書キーのパスフレーズ: このプロパティには、SSL クライアント秘密鍵のパスフレーズを指定します。
11. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
12. [次へ] をクリックします。
[認証] セクションで、認証の詳細を入力します。
1. [認証タイプ] を選択し、関連する詳細を入力します。
  Azure Synapse 接続でサポートされる認証タイプは次のとおりです。
  - ユーザーパスワード
  - Azure AD
2. [次へ] をクリックします。
Review: 接続と認証の詳細を確認します。
[作成] をクリックします。

認証を構成する

使用する認証に基づいて詳細を入力します。

ユーザーパスワード
- ユーザー名: データベースのユーザー名を入力します。
- パスワード: ユーザー名に関連付けられたパスワードを含む Secret Manager の Secret。

Azure AD
- クライアント ID: アクセストークンのリクエストに使用されるクライアント ID。これは、Azure ポータルで作成された接続アプリの概要で確認できます。
- スコープ: 必要なスコープのカンマ区切りのリスト。
- クライアントシークレット: アカウントのアクセスキーを含む Secret Manager のシークレット。
- 承認 URL: クライアントの作成時に生成された承認 URL。

接続作成後の追加手順

認証に OAuth 2.0 - Authorization code を選択した場合は、接続の作成後に次の追加の手順を行う必要があります。

接続ページで、新しく作成された接続を見つけます。
新しいコネクタの [ステータス] は [承認が必要] になります。
[承認が必要] をクリックします。
これにより、[承認の編集] ペインが表示されます。
[リダイレクト URI] の値を外部アプリケーションにコピーします。
認可の詳細を確認します。
[Authorize（承認）] をクリックします。
認可が成功すると、[接続] ページの接続ステータスが「有効」に設定されます。

認証コードの再認可

Authorization code 認証タイプを使用しているユーザーが、Azure Synapse アプリケーションの構成を変更した場合は、Azure Synapse 接続を再認可する必要があります。接続を再認可するには、次の手順を行います。

[接続] ページで必要な接続をクリックします。
これにより、[接続の詳細] ページが開きます。
[編集] をクリックして、接続の詳細を編集します。
[認証] セクションで [OAuth 2.0 - 認証コード] の詳細を確認します。
必要に応じて必要な変更を加えます。
[保存] をクリックします。接続の詳細ページに移動します。
[認証] セクションで [承認の編集] をクリックします。これにより、[承認] ペインが表示されます。
[Authorize（承認）] をクリックします。
認可が成功すると、[接続] ページの接続ステータスが「有効」に設定されます。

エンティティ、オペレーション、アクション

すべての Integration Connectors が、接続されたアプリケーションのオブジェクトを抽象化するレイヤを提供します。アプリケーションのオブジェクトには、この抽象化を通じてのみアクセスできます。抽象化は、エンティティ、オペレーション、アクションとして公開されます。

エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベースコネクタでは、テーブルがエンティティであり、ファイルサーバーコネクタでは、フォルダがエンティティです。また、メッセージングシステムコネクタでは、キューがエンティティです。
ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。
オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。
- リスト
- 取得
- 作成
- 更新
- 削除
使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティオペレーションをご覧ください。ただし、コネクタがいずれかのエンティティオペレーションをサポートしていない場合、サポートされていないオペレーションは Operations リストに含まれません。
アクション: コネクタインターフェースを介して統合で使用できる主要な関数の一つです。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。通常、アクションには入力パラメータと出力パラメータがあります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

システムの上限

Azure Synapse コネクタは、ノードごとに 1 秒あたり最大 4 件のトランザクションを処理でき、この上限を超えるトランザクションはすべてスロットルされます。デフォルトでは、Integration Connectors は、接続に 2 つのノードを割り当てます（可用性を高めるため）。

Integration Connectors に適用される上限の詳細については、上限をご覧ください。

注: Integration Connectors ノードの数は、使用状況に応じて動的に自動スケーリングされます。ただし、自動スケーリングを待たずに大量の容量を確保する場合は、接続の最小ノード値を調整できます。1 つの接続により多くのトランザクションを処理するには、より多くのノードが必要です。逆に、接続が処理するトランザクションが少ない場合は、必要なノードの数が少なくなります。ノードの値を構成するには、次の手順を行います。

従量課金制をご利用のお客様は、接続の編集ページでノードの最小値と最大値を構成します。
サブスクリプションベースで利用されているお客様は、サポートにお問い合わせください。

ノードが処理できる最大トランザクションは、さまざまな要因によって異なります。そのため、スループットを高めるために最小ノードを調整する前に、バックエンドシステムが必要なトラフィックを処理するために最適に設定されているかどうかを確認することをおすすめします。

サポートされているデータ型

このコネクタでサポートされているデータ型は次のとおりです。

BIGINT
BINARY
BIT
CHAR
DATE
DATETIME
DATETIME2
DATETIMEOFFSET
DECIMAL
FLOAT
DECIMAL
FLOAT
INT
MONEY
NCHAR
NVARCHAR
REAL
LSEG
SMALLDATETIME
SMALLINT
SMALLMONEY
TINYINT
UNIQUEIDENTIFIER
VARBINARY
VARCHAR

操作

Azure Synapse コネクタを使用すると、Azure Synapse でサポートされている形式でストアドプロシージャとカスタム SQL クエリを実行できます。カスタム SQL クエリを実行するため、コネクタは [カスタムクエリを実行する] アクションを備えています。

カスタムクエリを作成する手順は次のとおりです。

詳細な手順に沿って、コネクタタスクを追加します。
コネクタタスクを構成するときに、実行するアクションの種類で [Actions] を選択します。
[Actions] リストで [Execute custom query] を選択し、[Done] をクリックします。
[Task input] セクションを開き、次の操作を行います。
1. [タイムアウト後] フィールドに、クエリが実行されるまで待機する秒数を入力します。
  デフォルト値: 180 秒
2. [最大行数]フィールドに、データベースから返される最大行数を入力します。
  デフォルト値: 25。
3. カスタムクエリを更新するには、[Edit Custom Script] をクリックします。[Script editor] ダイアログが開きます。
4. [Script editor] ダイアログで、SQL クエリを入力して [Save] をクリックします。
  SQL ステートメントで疑問符（?）を使用して、クエリパラメータリストで指定する必要がある 1 つのパラメータを表すことができます。たとえば、次の SQL クエリは、LastName 列に指定された値と一致する Employees テーブルからすべての行を選択します。
```
SELECT * FROM Employees where LastName=?
```
  注: データ操作言語（DML）とデータ定義言語（DDL）のステートメントがサポートされています。
5. SQL クエリで疑問符を使用した場合は、各疑問符の [+ パラメータ名を追加] をクリックして、パラメータを追加する必要があります。統合の実行中に、これらのパラメータにより SQL クエリ内の疑問符（?）が順番に置き換わります。たとえば、3 つの疑問符（?）を追加した場合、3 つのパラメータを順番に追加する必要があります。
  
  クエリパラメータを追加する手順は次のとおりです。
  1. [Type] リストから、パラメータのデータ型を選択します。
  2. [値] フィールドに、パラメータの値を入力します。
  3. 複数のパラメータを追加するには、[+ クエリパラメータを追加] をクリックします。

エンティティオペレーションの例

例 - エンティティのレコードを一覧表示する

この例では、Users エンティティのレコードを一覧表示します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Users を選択します。
[List] オペレーションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、要件に応じて filterClause を設定できます。

たとえば、フィルタ句を employeeCode='5100' and startDate='2010-01-01 00:00:00' に設定すると、employeeCode が 5100 であり、startDate が 2010-01-01 00:00:00 であるレコードのみが一覧表示されます。

例 - エンティティから 1 つのレコードを取得する

この例では、Users エンティティからレコードを取得します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から User を選択します。
[Get] オペレーションを選択してから、[完了] をクリックします。
[コネクタタスクの [タスク入力 セクションで [entityId] をクリックし、[デフォルト値] フィールドに 103032 を入力します。
ここで、103032 は Users エンティティの主キー値です。

例 - エンティティからレコードを削除する

この例では、Users エンティティからレコードを削除します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Users を選択します。
[Delete] オペレーションを選択してから、[完了] をクリックします。
[コネクタタスクの [タスク入力] セクションの [entityId] をクリックし、[デフォルト値] フィールドに 113132 を入力します。
または、エンティティに複合主キーがある場合、entityId を指定する代わりに、filterClause を設定できます。たとえば、employeeCode='5100' and startDate='2010-01-01 00:00:00' です。

例 - エンティティにレコードを作成する

この例では、Users エンティティにレコードを作成します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Users を選択します。
[Create] オペレーションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"employeeCode": "5100",
"startDate": "2010-01-01 00:00:00.0",
"country": "US"
}
```

統合が成功すると、コネクタタスクの connectorOutputPayload フィールドに create オペレーションのレスポンスが返されます。

例 - エンティティ内のレコードを更新する