Oracle DB（バージョン 2）

Oracle DB コネクタを使用すると、Oracle データベース（バージョン 11.2 以降）インスタンスに接続し、サポートされているデータベースオペレーションを実行できます。

始める前に

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

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. コネクタ: 使用可能なコネクタのプルダウンリストから [Oracle DB] を選択します。
2. コネクタのバージョン: 使用可能なバージョンのプルダウンリストからバージョン 2 を選択します。
3. [接続名] フィールドに、接続インスタンスの名前を入力します。
  接続名は次の条件を満たす必要があります。
  - 接続名には英字、数字、ハイフンを使用できます。
  - 文字は小文字のみを使用できます。
  - 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
  - 接続名は 63 文字以内で指定してください。
4. 必要に応じて、接続インスタンスの [説明] を入力します。
5. 必要に応じて、Cloud Logging を有効にして、ログレベルを選択します。デフォルトのログレベルは Error に設定されています。
6. 必要に応じて、[Cloud Logging を有効にする] を選択して Cloud Logging を有効にします。
7. サービスアカウント: 必要なロールを持つサービスアカウントを選択します。
8. 必要に応じて、接続ノードの設定を構成します。
  - ノードの最小数: 接続ノードの最小数を入力します。
  - ノードの最大数: 接続ノードの最大数を入力します。
  ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。
9. Oracle DB 接続がサーバーベースの接続と TNS 接続のどちらを使用するかに基づいて、ServiceName または ServiceName（TNS 接続文字列）を指定します。両方を指定すると、DataSource が使用されます。
  - ServiceName: サーバーベースの認証を使用する場合は、サービス名と宛先の詳細を指定します。
  - DataSource: TNS 接続を使用する場合は、Oracle Net サービス名、Connect Descriptor（TNS Connect 文字列とも呼ばれます）、または接続先のデータベースを識別する簡単な接続名を指定します。宛先の詳細を指定する必要はありません。TNS 接続文字列を指定するには、次の形式を使用します: (DESCRIPTION=(ADDRESS=(protocol_address_information))(CONNECT_DATA= (SERVICE_NAME=service_name)))
10. 必要に応じて、[Include Synonyms] を選択します。
11. 放棄済み接続タイムアウト: 借用した接続が放棄済みとみなされる前に未使用にしておける期間を指定するタイムアウト値（秒単位）を入力します。
12. 非アクティブな接続タイムアウト: 接続タイムアウト値（秒単位）を入力します。
13. 最大接続再利用時間: 接続再利用時間（秒単位）を入力します。
14. TTL 接続タイムアウト: 接続が引き続き使用できる最大時間（秒単位）を入力します。
15. 閲覧可能なスキーマ: エンティティとアクションの取得時に使用するスキーマ名をカンマ区切りで入力します。例: schemaA, schemaB, schemaC
16. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
17. [NEXT] をクリックします。
[宛先] セクションに、接続するリモートホスト（バックエンドシステム）の詳細を入力します。
1. 宛先の種類: 宛先の種類を選択します。
  - リストから [ホストアドレス] を選択して、宛先のホスト名または IP アドレスを指定します。
  - バックエンドシステムへのプライベート接続を確立する場合は、リストからエンドポイントアタッチメントを選択し、次にエンドポイントアタッチメントリストから必要なエンドポイントアタッチメントを選択します。
    注: エンドポイントアタッチメントの作成方法については、PSC サービスアタッチメントとエンドポイントアタッチメントをご覧ください。エンドポイントアタッチメントを作成すると、[エンドポイントアタッチメント] リストに表示されます。
  セキュリティをさらに強化してバックエンドシステムへのパブリック接続を確立する場合は、接続用の静的アウトバウンド IP アドレスの構成を検討してから、特定の静的 IP アドレスのみを許可リストに登録するようファイアウォールルールを構成します。
  
  他の宛先を入力するには、[+ 宛先を追加] をクリックします。
2. [NEXT] をクリックします。
[認証] セクションで、認証の詳細を入力します。
1. [認証タイプ] を選択し、関連する詳細を入力します。
  Oracle DB 接続でサポートされる認証タイプは次のとおりです。
  - ユーザー名とパスワードを指定する
2. [NEXT] をクリックします。
Review: 接続と認証の詳細を確認します。
[作成] をクリックします。

認証を構成する

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

ユーザー名とパスワード
- ユーザー名: 認証に使用される Oracle アカウントのユーザー名。
- パスワード: Oracle アカウントのユーザー名に関連付けられたパスワードを含む Secret Manager の Secret。

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

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

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

システムの上限

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

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

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

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

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

サポートされるデータタイプ

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

BIGINT
BINARY
BIT
BOOLEAN
CHAR
DATE
DECIMAL
DOUBLE
FLOAT
INTEGER
LONGN VARCHAR
LONG VARCHAR
NCHAR
NUMERIC
NVARCHAR
REAL
SMALL INT
時間
TIMESTAMP
TINY INT
VARBINARY
VARCHAR

操作

Oracle DB コネクタを使用すると、Oracle データベースでサポートされている形式でストアドプロシージャ、関数、カスタム 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. 複数のパラメータを追加するには、[+ クエリパラメータを追加] をクリックします。

カスタムクエリアクションの使用方法については、アクションの例をご覧ください。

アクションの例

このセクションでは、このコネクタでいくつかのアクションを実行する方法について説明します。

例 - GROUP BY クエリを実行する

[Configure connector task] ダイアログで、[アクション] を選択します。
[カスタムクエリを実行] アクションを選択して、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、[カスタムクエリの編集] をクリックします。[カスタムクエリ] ダイアログが開きます。
[カスタムクエリ] ダイアログで、次の SQL クエリを入力し、[保存] をクリックします。
```
      Select E.EMPLOYEE_ID, E.EMPLOYEE_NAME, E.CITY
      FROM EMPLOYEES E
      LEFT JOIN EMPLOYEE_DEPARTMENT ED ON E.EMPLOYEE_ID=ED.ID 
      WHERE E.EMPLOYEE_NAME = 'John'
      GROUP BY E.CITY,E.EMPLOYEE_ID,E.EMPLOYEE_NAME
    
```
この例では、EMPLOYEES テーブルと EMPLOYEE_DEPARTMENT テーブルから従業員レコードを選択します。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータにクエリ結果セットが設定されます。

例 - パラメータ化されたクエリを実行する

[Configure connector task] ダイアログで、[アクション] を選択します。
[カスタムクエリを実行] アクションを選択して、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、フィールドに次の値を設定します。
1. タイムアウト時間: 10
2. 最大行数: 3
[+ パラメータ名を追加] をクリックして、次の値を入力します。
1. タイプ: VARCHAR
2. 値: John
[カスタムクエリを編集] をクリックします。[カスタムクエリ] ダイアログが開きます。

[カスタムクエリ] ダイアログで、次の SQL クエリを入力し、[保存] をクリックします。

  Select C.ID,C.NAME,C.CITY,C.O_DATE,E.EMPLOYEE_ID 
  FROM customqueries C,Employees E 
  WHERE C.ID=E.Employee_id and C.NAME=?

この例では、従業員の名前が John である従業員レコードを選択します。従業員の名前はパラメータ化されています。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"NAME": "John",
"O_DATE": "2023-06-01 00:00:00.0",
"EMPLOYEE_ID": 1.0
}, {
"NAME": "John",
"O_DATE": "2021-07-01 00:00:00.0",
"EMPLOYEE_ID": 3.0
}, {
"NAME": "John",
"O_DATE": "2022-09-01 00:00:00.0",
"EMPLOYEE_ID": 4.0
}]

例 - シーケンス値を使用してレコードを挿入する

[Configure connector task] ダイアログで、[アクション] を選択します。
[カスタムクエリを実行] アクションを選択して、[完了] をクリックします。
[カスタムクエリ] ダイアログで、次の SQL クエリを入力し、[保存] をクリックします。
```
  INSERT INTO AUTHOR(id,title) VALUES(author_table_id_seq.NEXTVAL,'Sample_book_title')
```

この例では、既存の author_table_id_seq シーケンスオブジェクトを使用して、AUTHOR テーブルにレコードを挿入します。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
}]

例 - 集計関数を使用してクエリを実行する

[Configure connector task] ダイアログで、[アクション] を選択します。
[カスタムクエリを実行] アクションを選択して、[完了] をクリックします。
[カスタムクエリ] ダイアログで、次の SQL クエリを入力し、[保存] をクリックします。
```
  SELECT SUM(SALARY) as Total FROM EMPLOYEES
  
```

この例では、EMPLOYEES テーブルの給与の集計値を計算します。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"TOTAL": 13000.0
}]

例 - 新しいテーブルを作成する

[Configure connector task] ダイアログで、[アクション] を選択します。
[カスタムクエリを実行] アクションを選択して、[完了] をクリックします。
[カスタムクエリ] ダイアログで、次の SQL クエリを入力し、[保存] をクリックします。
```
    CREATE TABLE TEST1 (ID INT, NAME VARCHAR(40),DEPT VARCHAR(20),CITY VARCHAR(10))
 
```

この例では、TEST1 テーブルを作成します。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
}]

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

例 - 全従業員を一覧表示する

この例では、Employee エンティティ内のすべての従業員を一覧表示します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Employee を選択します。
[List] オペレーションを選択してから、[完了] をクリックします。
必要に応じて、コネクタタスクの [タスク入力] セクションでフィルタ句を指定して、結果セットをフィルタリングできます。

例 - 従業員の詳細を取得する

この例では、Employee エンティティから、ID が 45 の従業員の詳細を取得します。

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

例 - 従業員レコードを作成する

この例では、Employee エンティティに新しい従業員レコードを追加します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Employee を選択します。
[Create] オペレーションを選択し、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Value フィールドに次のような値を入力します。
```
{
"EMPLOYEE_ID": 69.0,
"EMPLOYEE_NAME": "John",
"CITY": "Bangalore"
}
```
統合に成功すると、コネクタタスクの connectorOutputPayload フィールドには次と似たような値が含まれます。
```
 {
"ROWID": "AAAoU0AABAAAc3hAAF"
}
```

例 - 従業員レコードを更新する

この例では、Employee エンティティでの ID が 69 である従業員レコードを更新します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Employee を選択します。
[Update] オペレーションを選択し、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Value フィールドに次のような値を入力します。
```
{
"EMPLOYEE_NAME": "John",
"CITY": "Mumbai"
}
```
[entityId] をクリックし、[entityId] フィールドに「69」と入力します。
[entityId] を指定する代わりに、[entityId] を 69 に設定することもできます。

統合に成功すると、コネクタタスクの connectorOutputPayload フィールドの値は次のようになります。
```
{
}
```

例 - 従業員レコードを削除する

この例では、Employee エンティティで ID が 35 である従業員レコードを削除します。

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

Terraform を使用して接続を作成する

Terraform リソースを使用して、新しい接続を作成できます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

接続作成用の Terraform テンプレートのサンプルを表示するには、サンプルテンプレートをご覧ください。

Terraform を使用してこの接続を作成する場合は、Terraform 構成ファイルで次の変数を設定する必要があります。

パラメータ名	データ型	必須	説明
service_name	STRING	False	Oracle データベースのサービス名。
data_source	STRING	False	Oracle Net サービス名、Connect Descriptor（TNS Connect 文字列とも呼ばれます）、接続先のデータベースを識別する簡単な接続名。
include_synonyms	BOOLEAN	False	類義語についてメタデータをクエリし、エンティティとして利用できるようにします。このプロパティを false に設定すると、メタデータのパフォーマンスが向上する可能性があります。
abandoned_connection_timeout	INTEGER	False	放棄された接続タイムアウト（秒単位）は、借用した接続が放棄済みとみなされ、接続プールによって再利用されるまでの間に未使用にしておく時間を決定します。
inactive_connection_timeout	INTEGER	False	非アクティブな接続タイムアウト（秒単位）は、使用可能な接続がプールから削除されるまでに接続プールに保持される時間を決定します。
max_connection_reuse_time	INTEGER	False	最大接続再利用時間（秒単位）は、プールが接続を削除してからクローズするまでの、接続を再利用できる最大時間を指定します。
ttl_connection_timeout	INTEGER	False	接続が引き続き使用できる最大時間（秒単位）。
browsable_schemas	STRING	False	カンマ区切りのスキーマ（例: SchemaA、SchemaB など）を使用して、接続のエンティティとアクションを取得するときに使用します。デフォルトでユーザーのスキーマを使用します

統合で Oracle DB 接続を使用する

接続を作成すると、Apigee Integration と Application Integration の両方で使用できるようになります。この接続は、コネクタタスクを介して統合で使用できます。

Apigee Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。
Application Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。

Google Cloud コミュニティの助けを借りる

Google Cloud コミュニティの Cloud フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。