ボックス

Box コネクタを使用すると、Box バックエンドに接続し、SQL を使用して Box データを取得、更新できます。

サポート対象バージョン

このコネクタは、Box Content API バージョン 2.0 をサポートしています。

準備

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

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. [NEXT] をクリックします。
[接続の詳細] セクションで、次の操作を行います。
1. コネクタ: 使用可能なコネクタのプルダウンリストから [Box] を選択します。
2. コネクタのバージョン: 使用可能なバージョンのプルダウンリストからコネクタのバージョンを選択します。
3. [接続名] フィールドに、接続インスタンスの名前を入力します。
  接続名は次の条件を満たす必要があります。
  - 接続名には英字、数字、ハイフンを使用できます。
  - 文字は小文字のみを使用できます。
  - 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
  - 接続名は 63 文字以内で指定してください。
4. 必要に応じて、接続インスタンスの [説明] を入力します。
5. サービスアカウント: 必要なロールを持つサービスアカウントを選択します。
6. 必要に応じて、接続ノードの設定を構成します。
  - ノードの最小数: 接続ノードの最小数を入力します。
  - ノードの最大数: 接続ノードの最大数を入力します。
  ノードは、トランザクションを処理する接続の単位（またはレプリカ）です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され（可用性を高めるため）、最大ノード数は 50 に設定されます。
7. なりすましユーザーモード: ユーザーのなりすましのタイプを指定します。ユーザーモードか管理モードかを指定します。
8. Use proxy: このチェックボックスを選択して、接続用のプロキシサーバーを構成し、次の値を構成します。
9. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
10. [NEXT] をクリックします。
[認証] セクションで、認証の詳細を入力します。
1. [認証タイプ] を選択し、関連する詳細を入力します。
  Box 接続でサポートされる認証タイプは次のとおりです。
  - OAuth 2.0 - クライアント認証情報
  - OAuth 2.0 - 認証コード
2. [NEXT] をクリックします。
Review: 接続と認証の詳細を確認します。
[作成] をクリックします。

認証を構成する

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

OAuth 2.0 - クライアント認証情報
- クライアント ID: 作成したアプリのコネクタから提供されるクライアント ID。
- クライアントシークレット: 作成した接続されているアプリのクライアントシークレットを含む Secret Manager のシークレットです。
- 秘密鍵: 秘密鍵ファイルの内容を格納する Secret Manager のシークレット。秘密鍵は、コネクタに提供された公開鍵 / 証明書と一致する必要があります。
- 秘密鍵パスワード: 秘密鍵ファイルのパスワード（言い回し）を含む Secret Manager の Secret。
- Box アプリケーションのアクセスレベル: Box アプリのアプリケーションアクセスレベル
- Enterprise Id/User Id: アプリレベルがエンタープライズの場合はエンタープライズ ID、アプリレベルがユーザーの場合はユーザー ID
- OAuth JWT 公開鍵 ID: JWT の公開鍵の ID。
- Auth スキーム: Box Connector の認証スキーム
- OAuth を初期化する: Box Connector の OAuth パラメータを初期化します。
- OAuth JWT 証明書タイプ: Box Connector の OAuth JWT 証明書タイプ。
OAuth 2.0 - 認証コード

クライアント ID: 外部アプリケーションによって提供されるクライアント ID。
スコープ: 権限スコープ。例: root_readonlyスコープの仕組みと Box で利用可能なすべてのスコープを確認するには、スコープをご覧ください。
クライアントシークレット: Secret Manager のシークレットを選択します。この認証を構成する前に、Secret Manager のシークレットを作成しておく必要があります。
シークレットのバージョン: クライアントシークレットの Secret Manager シークレットのバージョン。

Authorization code 認証タイプの場合は、接続を作成した後、認証を構成するためにいくつかの追加手順を行う必要があります。詳しくは、接続作成後の追加手順をご覧ください。

注: Authorization code 認証タイプを使用していて、Box のアプリケーションで構成を変更した場合は、Box の接続を再承認する必要があります。再承認する方法については、認証コードの再承認をご覧ください。

接続作成後の追加手順

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

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

認証コードの再認可

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

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

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

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

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

アクション

このセクションでは、Box 接続でサポートされているすべてのアクションを一覧表示します。

DownloadFile アクション

このアクションを行うと、Box インスタンスからファイルをダウンロードできます。

DownloadFile アクションの入力パラメータ

パラメーター名	データ型	必須	説明
FileID	文字列	はい	ダウンロードするファイルの ID。
HasBytes	ブール値	はい	ファイルを文字列としてダウンロードするか、Base64 エンコード文字列としてダウンロードするかを指定します。

DownloadFile アクションの出力パラメータ

このアクションは、結果を示すレスポンスの本文でステータス 200（OK）を返します。

パラメーター名	データ型	説明
完了	文字列	ファイルのダウンロードが成功したかどうかを指定します。
ContentBytes	文字列	Base64 でエンコードされた文字列としてのファイルコンテンツ。

DownloadFile アクションの構成方法の例については、アクションの例をご覧ください。

UploadFile アクション

このアクションでは、Box インスタンスにファイルをアップロードできます。

UploadFile アクションの入力パラメータ

パラメーター名	データ型	必須	説明
ParentID	文字列	はい	ファイルをアップロードするフォルダの ID。このパラメータを指定しない場合、ファイルは Box アカウントのルートにアップロードされます。デフォルト値は 0 です。
内容	文字列	はい	アップロードするファイルコンテンツ。

UploadFile アクションの出力パラメータ

このアクションは、結果を示すレスポンスの本文でステータス 200（OK）を返します。

パラメーター名	データ型	説明
完了	文字列	ファイルのアップロードが成功したかどうかを示します。
ID	文字列	新しく作成されたファイルの ID。
VersionID	文字列	ファイルの特定のバージョンの ID。
Hash	文字列	ファイルの `SHA1` ハッシュ。
etag	文字列	ファイルまたはフォルダの ETag 値。デフォルト値は 0 です。

UploadFile アクションの構成方法の例については、アクションの例をご覧ください。

CopyFile アクション

このアクションを行うと、Box インスタンスからファイルをコピーできます。

CopyFile アクションの入力パラメータ

パラメーター名	データ型	必須	説明
FileID	文字列	はい	コピーするファイルの ID。
DestinationFolderId	文字列	いいえ	ファイルのコピー先のフォルダの ID。値を指定しない場合は、ファイルの最新バージョンがコピーされます。
NewName	文字列	はい	コピーしたファイルの新しいファイル名。

CopyFile アクションの出力パラメータ

このアクションは、結果を示すレスポンスの本文でステータス 200（OK）を返します。

パラメーター名	データ型	説明
完了	文字列	ファイルのコピーが成功したかどうかを示します。
ID	文字列	コピーしたファイルの ID。

CopyFile アクションの構成方法の例については、アクションの例をご覧ください。

CopyFolder アクション

このアクションでは、Box インスタンスからフォルダ全体をコピーできます。

CopyFolder アクションの入力パラメータ

パラメーター名	データ型	必須	説明
FolderID	文字列	はい	コピーするフォルダの ID。
DestinationFolderId	文字列	はい	フォルダのコピー先のフォルダの ID。
NewName	文字列	いいえ	コピーしたフォルダの新しいファイル名。

CopyFolder アクションの出力パラメータ

このアクションは、結果を示すレスポンスの本文でステータス 200（OK）を返します。

パラメーター名	データ型	説明
完了	文字列	フォルダのコピーが成功したかどうかを示します。
ID	文字列	コピーしたフォルダの ID。

CopyFolder アクションの構成方法の例については、アクションの例をご覧ください。

アクションの例

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

例 - ファイルをダウンロードする

[Configure connector task] ダイアログで、[Actions] をクリックします。
[DownloadFile] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"FileID": "1283194869422",
"HasBytes": true
}
```

この例では、Base64 でエンコードされた文字列としてファイルをダウンロードします。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[
{ "Success": "True"},
{"ContentBytes": "JVBERi0xLjQKJcfl9OXwCjIgMCBvYmoKJSBbMjRdIAo8PAovRmlsdGVy"}
]

注: 非バイナリファイルをダウンロードする場合は、HasBytes 値を false に設定します。

例 - ファイルをアップロードする

[Configure connector task] ダイアログで、[Actions] をクリックします。
[UploadFile] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"ParentId": "0",
"Content": "12345"
}
```

この例では、文字列のコンテンツをファイルとしてアップロードします。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Success": "true",
"ID": "1283902965389",
"VersionID": "1403546001389",
"Hash": "8cb2237d0679ca88db6464eac60da96345513964",
"Etag": "0"
}]

例 - ファイルをコピーする

[Configure connector task] ダイアログで、[Actions] をクリックします。
[CopyFile] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"FileID": "1288751886061",
"DestinationFolderId": "219105724517",
"NewName": "NewCopiedFile"
}
```

この例では、ID が 1288751886061 のファイルを ID が 219105724517 のフォルダにコピーします。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Success": "true",
"ID": "1308006018536"
}]

例 - フォルダをコピーする

[Configure connector task] ダイアログで、[Actions] をクリックします。
[CopyFolder] アクションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
"FolderID": "218475301279",
"DestinationFolderId": "0",
"NewName": "NewCopiedFolder"
}
```

この例では、ID が 218475301279 のフォルダを ID が 219105724517 のフォルダにコピーします。アクションが成功すると、コネクタタスクの connectorOutputPayload レスポンスパラメータの値は次のようになります。

[{
"Success": "true",
"ID": "226312444517"
}]

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

例 - すべてのファイルを一覧表示する

この例では、Files エンティティ内のファイルを一覧表示します。

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

例 - チケットを取得する

この例では、Tickets エンティティから特定のチケットを取得します。

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

例 - チケットを作成する

この例では、Tickets エンティティにチケットを作成します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
Entity から Tickets を選択します。
[Create] オペレーションを選択してから、[完了] をクリックします。

[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。

{
"Subject": "Create_Ticket_01",
"Description": "Test",
"Type": "incident",
"Priority": "urgent",
"Status": "open",
"Recipient": null,
"HasIncidents": false,
"DueAt": null,
"RequesterId": 3.84625885158E11,
"SubmitterId": 3.84625883418E11,
"AssigneeId": 3.84625883418E11,
"OrganizationId": "16665992392721",
"GroupId": 3.60008282358E11,
"TicketFormId": 3.60001719218E11,
"BrandId": 3.60003285058E11
}

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

{
"Id": 38.0
}

例 - チケットを更新する

この例では、Tickets エンティティで指定されたチケットを更新します。

[Configure connector task] ダイアログで、[Entities] をクリックします。
[Entity] リストからチケットを選択します。
[Update] オペレーションを選択してから、[完了] をクリックします。
[コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
```
{
        "Subject": "Update_Ticket_02",
        "Description": "Updating the ticket",
        "RequesterId": 1.6854335860497E13
      }
      
```
[entityId] をクリックし、[デフォルト値] フィールドに「35」と入力します。
[entityId] を指定する代わりに、[filterClause] を 35 に設定することもできます。

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

例 - チケットを削除する

この例では、指定したチケットを Tickets エンティティから削除します。

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

注: Delete オペレーションでは、レコードの削除のみを行います。必要に応じて、削除したレコードを後で復元できます。

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

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

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

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

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

パラメータ名	データ型	必須	説明
impersonate_user_mode	ENUM	True	ユーザーのなりすましのタイプを指定します。ユーザーモードか管理モードかを指定します。指定できる値は、User、Admin です。
proxy_enabled	BOOLEAN	False	接続用のプロキシサーバーを構成するには、このチェックボックスをオンにします。
proxy_auth_scheme	ENUM	False	ProxyServer プロキシへの認証に使用する認証タイプです。サポートされている値は、BASIC、DIGEST、NONE です。
proxy_user	文字列	False	ProxyServer プロキシへの認証に使用されるユーザー名です。
proxy_password	SECRET	False	ProxyServer プロキシの認証に使用されるパスワード。
proxy_ssltype	ENUM	False	ProxyServer プロキシへの接続時に使用する SSL のタイプです。サポートされている値は AUTO、ALWAYS、NEVER、TUNNEL です。

統合で Box 接続を使用する

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

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

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

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

ボックス

サポート対象バージョン

準備

コネクタを構成する

認証を構成する

接続作成後の追加手順

認証コードの再認可

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

アクション

DownloadFile アクション

DownloadFile アクションの入力パラメータ

DownloadFile アクションの出力パラメータ

UploadFile アクション

UploadFile アクションの入力パラメータ

UploadFile アクションの出力パラメータ

CopyFile アクション

CopyFile アクションの入力パラメータ

CopyFile アクションの出力パラメータ

CopyFolder アクション

CopyFolder アクションの入力パラメータ

CopyFolder アクションの出力パラメータ

アクションの例

例 - ファイルをダウンロードする

例 - ファイルをアップロードする

例 - ファイルをコピーする

例 - フォルダをコピーする

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

例 - すべてのファイルを一覧表示する

例 - チケットを取得する

例 - チケットを作成する

例 - チケットを更新する

例 - チケットを削除する

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

統合で Box 接続を使用する

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

次のステップ

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