ID コネクタを作成する

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

デフォルトでは、Google Cloud Search は Google Cloud Directory(ユーザーとグループ)に保存されている Google ID のみを認識します。ID コネクタは、企業の ID を Google Cloud Search で使用される Google ID と同期させるために使用されます。

Google は、ID コネクタを開発するための以下のオプションを提供しています。

  • Identity Connector SDK。このオプションは、Java プログラミング言語でプログラミングしているデベロッパーを対象としています。Identity Connector SDK は、コネクタをすばやく作成するための REST API を簡単に使えるようにしたラッパーです。この SDK で ID コネクタを作成する場合は、Identity Connector SDK を使用して ID コネクタを作成するをご覧ください。

  • 低レベル REST API と API ライブラリ。これらのオプションは、Java でプログラミングしていないデベロッパーや、コードベースが REST API やライブラリに問題なく対応できるデベロッパー向けです。REST API を使用して ID コネクタを作成するには、Directory API: ユーザー アカウントでユーザーをマッピングする方法、Cloud Identity のドキュメントでグループのマッピングをご確認ください。

Identity Connector SDK を使用して ID コネクタを作成する

ID コネクタによって行われる標準的なタスクは、次のとおりです。

  1. コネクタを構成します。
  2. 企業 ID システムからすべてのユーザーを取得し、Google ID との同期のために Google に送信します。
  3. 企業 ID システムからすべてのグループを取得し、Google ID との同期のために Google に送信します。

依存関係を設定する

SDK を使用するには、ビルドファイルに特定の依存関係を含める必要があります。以下のタブをクリックすると、ビルド環境の依存関係が表示されます。

Maven

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-identity-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

Gradle

 compile group: 'com.google.enterprise.cloudsearch',
         name: 'google-cloudsearch-identity-connector-sdk',
         version: 'v1-0.0.3'

コネクタ構成を作成する

コネクタごとに対応する構成ファイルが存在し、コネクタはそこに含まれているパラメータ(お客様のリポジトリの ID など)を使用します。パラメータは api.sourceId=1234567890abcdef などの Key-Value ペアとして定義されます。

Google Cloud Search SDK には、すべてのコネクタで使用される Google 提供構成パラメータが複数含まれています。以下の Google 提供パラメータをお客様の構成ファイル内で宣言してください。

  • コンテンツ コネクタでは、api.sourceIdapi.serviceAccountPrivateKeyFile を宣言する必要があります。これらのパラメータは、リポジトリの場所と、リポジトリにアクセスするために必要な秘密鍵を識別するためです。
  • ID コネクタの場合、このパラメータで外部 ID のソースの場所を識別するため、api.identitySourceId を宣言する必要があります。ユーザーを同期する場合は、api.customerId を企業の Google Workspace アカウントの一意の ID として宣言する必要もあります。

Google 提供のその他のパラメータのデフォルト値をオーバーライドしたい場合を除き、構成ファイルで宣言する必要はありません。特定の ID やキーを生成する方法など、Google 提供の構成パラメータの詳細については、Google 提供の構成パラメータをご覧ください。

独自のリポジトリ パラメータを定義して、お客様の構成ファイル内で使用することもできます。

構成ファイルをコネクタに渡す

システム プロパティ config を設定して、構成ファイルをコネクタに渡します。コネクタの開始時に -D 引数を使用してプロパティを設定できます。たとえば、次のコマンドは、MyConfig.properties 構成ファイルを使用してコネクタを起動します。

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

この引数がない場合、SDK は connector-config.properties という名前のデフォルト構成ファイルへのアクセスを試みます。

テンプレート クラスを使用して完全同期 ID コネクタを作成する

Identity Connector SDK には、ID リポジトリのすべてのユーザーとグループを Google ID と同期するために使用できる FullSyncIdentityConnector テンプレート クラスが含まれています。このセクションでは、FullSyncIdentityConnector テンプレートを使用して、Google 以外の ID リポジトリのユーザーとグループを完全に同期する方法について説明します。

このセクションでは、IdentityConnecorSample.java サンプルのコード スニペットについて説明します。このサンプルでは、2 つの CSV ファイルからユーザー ID とグループ ID を読み取り、Google ID と同期します。

コネクタのエントリ ポイントを実装する

コネクタのエントリ ポイントは main() メソッドです。このメソッドの主なタスクは、Application クラスのインスタンスを作成し、その start() メソッドを呼び出してコネクタを実行することです。

application.start() を呼び出す前に、IdentityApplication.Builder クラスを使用して FullSyncIdentityConnector テンプレートをインスタンス化します。FullSyncIdentityConnector は、メソッドを実装する Repository オブジェクトを受け入れます。次のコード スニペットは、main() メソッドを実装する方法を示しています。

IdentityConnectorSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * sync connector. In the full sync case, the repository is responsible
 * for providing a snapshot of the complete identity mappings and
 * group rosters. This is then reconciled against the current set
 * of mappings and groups in Cloud Directory.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new CsvRepository();
  IdentityConnector connector = new FullSyncIdentityConnector(repository);
  IdentityApplication application = new IdentityApplication.Builder(connector, args).build();
  application.start();
}

SDK はバックグラウンドで、コネクタの main() メソッドが Application.build を呼び出した後に initConfig() メソッドを呼び出します。initConfig() メソッドは、次のタスクを実行します。

  1. Configuation.isInitialized() メソッドを呼び出して、Configuration が初期化されていないことを確認します。
  2. Google 提供の Key-Value ペアを使用して、Configuration オブジェクトを初期化します。各 Key-Value ペアは、Configuration オブジェクト内の ConfigValue オブジェクトに格納されます。

Repository インターフェースを実装する

Repository オブジェクトの唯一の目的は、リポジトリ ID と Google ID の同期を実行することです。テンプレートを使用する場合は、Repository インターフェース内の特定のメソッドをオーバーライドするだけで ID コネクタを作成できます。FullTraversalConnector では、次のメソッドをオーバーライドする可能性があります。

  • init() メソッド。ID リポジトリを設定して初期化するには、init() メソッドをオーバーライドします。

  • listUsers() メソッド。ID リポジトリ内のすべてのユーザーを Google ユーザーと同期するには、listUsers() メソッドをオーバーライドします。

  • listGroups() メソッド。ID リポジトリ内のすべてのグループを Google グループと同期するには、listGroups() メソッドをオーバーライドします。

  • (省略可)close() メソッド。リポジトリをクリーンアップする必要がある場合は、close() メソッドをオーバーライドします。このメソッドは、コネクタのシャットダウン時に 1 回呼び出されます。

カスタム構成パラメータを取得する

コネクタの構成を処理する一環として、Configuration オブジェクトからカスタム パラメータを取得する必要があります。このタスクは通常、Repository クラスの init() メソッドで実行されます。

Configuration クラスには、構成からさまざまなデータ型を取得するためのメソッドがいくつか用意されています。各メソッドは ConfigValue オブジェクトを返します。次に、ConfigValue オブジェクトの get() メソッドを使用して実際の値を取得します。次のスニペットは、Configuration オブジェクトから userMappingCsvPathgroupMappingCsvPath の値を取得する方法を示しています。

IdentityConnectorSample.java
/**
 * Initializes the repository once the SDK is initialized.
 *
 * @param context Injected context, contains convenienve methods
 *                for building users & groups
 * @throws IOException if unable to initialize.
 */
@Override
public void init(RepositoryContext context) throws IOException {
  log.info("Initializing repository");
  this.context = context;
  userMappingCsvPath = Configuration.getString(
      "sample.usersFile", "users.csv").get().trim();
  groupMappingCsvPath = Configuration.getString(
      "sample.groupsFile", "groups.csv").get().trim();
}

複数の値を含むパラメータを取得して解析するには、Configuration クラスの型パーサーのいずれかを使用して、データを個別のチャンクに解析します。次のスニペットは、チュートリアル コネクタからの getMultiValue メソッドを使用して、GitHub リポジトリ名のリストを取得します。

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

すべてのユーザーのマッピングを取得する

listUsers() をオーバーライドして、ID リポジトリからすべてのユーザーのマッピングを取得します。listUsers() メソッドは、最後に同期された ID を表すチェックポイントを受け入れます。チェックポイントは、プロセスが中断された場合に同期を再開する目的で使用できます。リポジトリ内のユーザーごとに、listUsers() メソッドで次の手順を実行します。

  1. Google ID および関連する外部 ID からなるマッピングを取得します。
  2. ペアを、listUsers() メソッドから返されたイテレータにパッケージ化します。

ユーザー マッピングを取得する

以下のコード スニペットは、CSV ファイルに保存されている ID マッピングを取得する方法を示しています。

IdentityConnectorSample.java
/**
 * Retrieves all user identity mappings for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the mappings. This is reconciled against the current mappings
 * in Cloud Directory. All identity mappings returned here are
 * set in Cloud Directory. Any previously mapped users that are omitted
 * are unmapped.
 *
 * The connector does not create new users. All users are assumed to
 * exist in Cloud Directory.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of user identity mappings
 * @throws IOException if unable to read user identity mappings
 */
@Override
public CheckpointCloseableIterable<IdentityUser> listUsers(byte[] checkpoint)
    throws IOException {
  List<IdentityUser> users = new ArrayList<>();
  try (Reader in = new FileReader(userMappingCsvPath)) {
    // Read user mappings from CSV file
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "primary_email", "external_id"
      String primaryEmailAddress = record.get(0);
      String externalId = record.get(1);
      if (primaryEmailAddress.isEmpty() || externalId.isEmpty()) {
        // Skip any malformed mappings
        continue;
      }
      log.info(() -> String.format("Adding user %s/%s",
          primaryEmailAddress, externalId));

      // Add the identity mapping
      IdentityUser user = context.buildIdentityUser(
          primaryEmailAddress, externalId);
      users.add(user);
    }
  }
  // ...
}

イテレータにユーザー マッピングをパッケージ化する

listUsers() メソッドは、IdentityUser オブジェクトの Iterator、具体的には CheckpointCloseableIterable を返します。CheckpointClosableIterableImpl.Builder クラスを使用して、イテレータを作成して返すことができます。以下のコード スニペットは、各マッピングをリストにパッケージ化して、そのリストからイテレータを構築する方法を示しています。

IdentityConnectorSample.java
CheckpointCloseableIterable<IdentityUser> iterator =
  new CheckpointCloseableIterableImpl.Builder<IdentityUser>(users)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

グループを取得する

ID リポジトリからすべてのグループとそのメンバーを取得するには、listGroups() をオーバーライドします。listGroups() メソッドは、最後に同期された ID を表すチェックポイントを受け入れます。チェックポイントは、プロセスが中断された場合に同期を再開する目的で使用できます。リポジトリ内のユーザーごとに、listGroups() メソッドで次の手順を実行します。

  1. グループとそのメンバーを取得します。
  2. 各グループとメンバーを、listGroups() メソッドで返されたイテレータにパッケージ化します。

グループ ID を取得する

以下のコード スニペットは、CSV ファイルに保存されているグループとメンバーを取得する方法を示しています。

IdentityConnectorSample.java
/**
 * Retrieves all group rosters for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the rosters. This is reconciled against the current rosters
 * in Cloud Directory. All groups and members  returned here are
 * set in Cloud Directory. Any previously created groups or members
 * that are omitted are removed.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of group rosters
 * @throws IOException if unable to read groups
 */    @Override
public CheckpointCloseableIterable<IdentityGroup> listGroups(byte[] checkpoint)
    throws IOException {
  List<IdentityGroup> groups = new ArrayList<>();
  try (Reader in = new FileReader(groupMappingCsvPath)) {
    // Read group rosters from CSV
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "group_id", "member"[, ..., "memberN"]
      String groupName = record.get(0);
      log.info(() -> String.format("Adding group %s", groupName));
      // Parse the remaining columns as group memberships
      Supplier<Set<Membership>> members = new MembershipsSupplier(record);
      IdentityGroup group = context.buildIdentityGroup(groupName, members);
      groups.add(group);
    }
  }
  // ...

}

グループとメンバーをイテレータにパッケージ化する

listGroups() メソッドは、IdentityGroup オブジェクトの Iterator、具体的には CheckpointCloseableIterable を返します。CheckpointClosableIterableImpl.Builder クラスを使用して、イテレータを作成して返すことができます。次のコード スニペットは、各グループとメンバーをリストにパッケージ化し、そのリストからイテレータを作成する方法を示しています。

IdentityConnectorSample.java
CheckpointCloseableIterable<IdentityGroup> iterator =
   new CheckpointCloseableIterableImpl.Builder<IdentityGroup>(groups)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

次の手順

必要に応じて次の手順を行います。