コネクタのデプロイ

この Cloud Search チュートリアルのページでは、データをインデックス登録するためのデータソースとコンテンツコネクタを設定する方法について説明します。このチュートリアルの最初から始めるには、Cloud Search スタートガイドのチュートリアルをご覧ください。

コネクタをビルドする

作業ディレクトリを cloud-search-samples/end-to-end/connector ディレクトリに変更し、次のコマンドを実行します。

mvn package -DskipTests

このコマンドは、コンテンツコネクタのビルドに必要な依存関係をダウンロードし、コードをコンパイルします。

サービスアカウントの認証情報を作成する

コネクタが Cloud Search API を呼び出すには、サービスアカウントの認証情報が必要です。認証情報を作成するには:

Google Cloud コンソールに戻ります。
左側のナビゲーションで [認証情報] をクリックします。[認証情報] ページが表示されます。
[+ 認証情報を作成] プルダウンリストをクリックし、[サービスアカウント] を選択します。[サービスアカウントの作成] ページが表示されます。
[サービスアカウント名] フィールドに「tutorial」と入力します。
サービスアカウント ID の値（サービスアカウント名の直後）をメモします。この値は後で使用します。
[作成] をクリックします。[サービスアカウントの権限（省略可）] ダイアログが表示されます。
[続行] をクリックします[ユーザーにこのサービスアカウントへのアクセスを許可する（省略可）] ダイアログが表示されます。
[完了] をクリックします。[認証情報] 画面が表示されます。
[サービスアカウント] で、サービスアカウントのメールアドレスをクリックします。[サービスアカウントの詳細] ページが表示されます。
[鍵] で、[鍵を追加] プルダウンリストをクリックし、[新しい鍵を作成] を選択します。[秘密鍵の作成] ダイアログが表示されます。
[作成] をクリックします。
（省略可）[console.cloud.google.com でダウンロードを許可しますか？] ダイアログが表示されたら、[許可] をクリックします。
秘密鍵ファイルがパソコンに保存されます。ダウンロードしたファイルの場所をメモします。このファイルは、Google Cloud Search APIs を呼び出すときに認証できるように、コンテンツコネクタを構成するために使用されます。

サードパーティのサポートを初期化する

他の Cloud Search API を呼び出す前に、Google Cloud Search のサードパーティサポートを初期化します。

サードパーティのサポートを初期化するには:

Cloud Search プラットフォームプロジェクトでウェブアプリケーションの認証情報を作成します。認証情報を作成するをご覧ください。クライアント ID とクライアントシークレットが必要です。
OAuth 2.0 Playground を使用してアクセストークンを取得します。
1. [OAuth 2.0 Configuration]（設定アイコン）をクリックし、[Use your own OAuth credentials] をオンにします。
2. クライアント ID とクライアントシークレットを入力します。
3. スコープフィールドに「https://www.googleapis.com/auth/cloud_search.settings」と入力し、[API を承認] をクリックします。
4. [Exchange authorization code for tokens] をクリックします。

次の curl コマンドを実行します。[YOUR_ACCESS_TOKEN] は実際のトークンに置き換えます。

curl --request POST \
'https://cloudsearch.googleapis.com/v1:initializeCustomer' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed

成功した場合、レスポンスの本文には operation が含まれます。失敗した場合は、Cloud Search サポートにお問い合わせください。

operations.get を使用して初期化を検証します。

curl 'https://cloudsearch.googleapis.com/v1/operations/<var>operation_name</var>?key=[YOUR_API_KEY]' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--header 'Accept: application/json' \
--compressed

done が true の場合、初期化は完了しています。

データソースを作成する

次に、管理コンソールでデータソースを作成します。データソースは、コネクタを使用してコンテンツをインデックス登録するための名前空間を提供します。

Google 管理コンソールを開きます。
アプリアイコンをクリックします。[アプリの管理] ページが表示されます。
[Google Workspace] をクリックします。[アプリ Google Workspace 管理] ページが表示されます。
下にスクロールして、[Cloud Search] をクリックします。[Google Workspace の設定] ページが表示されます。
[サードパーティのデータソース] をクリックします。[データソース] ページが表示されます。
黄色の丸い + をクリックします。[新しいデータソースを追加] ダイアログが表示されます。
[表示名] フィールドに「チュートリアル」と入力します。
[サービスアカウントのメールアドレス] フィールドに、前のセクションで作成したサービスアカウントのメールアドレスを入力します。サービスアカウントのメールアドレスがわからない場合は、サービスアカウントページで値を確認してください。
[追加] をクリックします。[データソースを作成しました] ダイアログが表示されます。
[OK] をクリックします。新しく作成したデータソースのソース ID をメモします。ソース ID は、コンテンツコネクタの構成に使用されます。

GitHub API の個人アクセストークンを生成する

コネクタには、十分な割り当てを確保するために、GitHub API への認証済みアクセスが必要です。簡素化のため、コネクタは OAuth ではなく個人用アクセストークンを使用します。個人用トークンを使用すると、OAuth と同様に、限られた権限セットを持つユーザーとして認証できます。

GitHub にログインします。
右上にあるプロフィール写真をクリックします。プルダウンメニューが表示されます。
[設定] をクリックします。
[デベロッパー向けの設定] をクリックします。
[Personal access tokens] をクリックします。
[Generate personal access token] をクリックします。
[メモ] フィールドに「Cloud Search チュートリアル」と入力します。
public_repo スコープを確認します。
[Generate token] をクリックします。
生成されたトークンをメモします。コネクタが GitHub API を呼び出すために使用され、インデックス登録を実行するための API 割り当てを提供します。

コネクタを構成する

認証情報とデータソースを作成したら、次の値を含めるようにコネクタ構成を更新します。

コマンドラインから cloud-search-samples/end-to-end/connector/ ディレクトリに移動します。
テキストエディタで sample-config.properties ファイルを開きます。
api.serviceAccountPrivateKeyFile パラメータを、先ほどダウンロードしたサービス認証情報のファイルパスに設定します。
api.sourceId パラメータを、前に作成したデータソースの ID に設定します。
github.user パラメータを GitHub ユーザー名に設定します。
github.token パラメータを、以前に作成したアクセストークンに設定します。
ファイルを保存します。

スキーマを更新する

コネクタは、構造化コンテンツと非構造化コンテンツの両方をインデックス登録します。データをインデックスに登録する前に、データソースのスキーマを更新する必要があります。次のコマンドを実行してスキーマを更新します。

mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.SchemaTool \
    -Dexec.args="-Dconfig=sample-config.properties"

コネクタを実行する

コネクタを実行してインデックス登録を開始するには、次のコマンドを実行します。

mvn exec:java -Dexec.mainClass=com.google.cloudsearch.tutorial.GithubConnector \
    -Dexec.args="-Dconfig=sample-config.properties"

コネクタのデフォルト構成では、googleworkspace 組織内の単一のリポジトリをインデックスに登録します。リポジトリのインデックス作成には約 1 分かかります。最初のインデックス登録の後、コネクタは Cloud Search インデックスに反映する必要があるリポジトリの変更を継続的にポーリングします。

コードの確認

残りのセクションでは、コネクタの構築方法について説明します。

アプリケーションの起動

コネクタのエントリポイントは GithubConnector クラスです。main メソッドは、SDK の IndexingApplication をインスタンス化して開始します。

GithubConnector.java

GitHub で表示

/**
 * Main entry point for the connector. Creates and starts an indexing
 * application using the {@code ListingConnector} template and the sample's
 * custom {@code Repository} implementation.
 *
 * @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 GithubRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args)
      .build();
  application.start();
}

SDK で提供される ListingConnector は、Cloud Search キューを活用してインデックス内のアイテムの状態を追跡する走査戦略を実装します。GitHub からコンテンツにアクセスするために、サンプルコネクタによって実装された GithubRepository に委任します。

GitHub リポジトリのトラバース

完全なトラバーサルの間、getIds() メソッドが呼び出され、インデックス登録が必要なアイテムがキューにプッシュされます。

コネクタは、複数のリポジトリまたは組織をインデックスに登録できます。障害の影響を最小限に抑えるため、GitHub リポジトリは一度に 1 つずつトラバースされます。チェックポイントは、トラバーサルの結果とともに返されます。このチェックポイントには、後続の getIds() 呼び出しでインデックス登録されるリポジトリのリストが含まれています。エラーが発生した場合、インデックス登録は最初からではなく、現在のリポジトリで再開されます。

GithubRepository.java

GitHub で表示

/**
 * Gets all of the existing item IDs from the data repository. While
 * multiple repositories are supported, only one repository is traversed
 * per call. The remaining repositories are saved in the checkpoint
 * are traversed on subsequent calls. This minimizes the amount of
 * data that needs to be reindex in the event of an error.
 *
 * <p>This method is called by {@link ListingConnector#traverse()} during
 * <em>full traversals</em>. Every document ID and metadata hash value in
 * the <em>repository</em> is pushed to the Cloud Search queue. Each pushed
 * document is later polled and processed in the {@link #getDoc(Item)} method.
 * <p>
 * The metadata hash values are pushed to aid document change detection. The
 * queue sets the document status depending on the hash comparison. If the
 * pushed ID doesn't yet exist in Cloud Search, the document's status is
 * set to <em>new</em>. If the ID exists but has a mismatched hash value,
 * its status is set to <em>modified</em>. If the ID exists and matches
 * the hash value, its status is unchanged.
 *
 * <p>In every case, the pushed content hash value is only used for
 * comparison. The hash value is only set in the queue during an
 * update (see {@link #getDoc(Item)}).
 *
 * @param checkpoint value defined and maintained by this connector
 * @return this is typically a {@link PushItems} instance
 */
@Override
public CheckpointCloseableIterable<ApiOperation> getIds(byte[] checkpoint)
    throws RepositoryException {
  List<String> repositories;
  // Decode the checkpoint if present to get the list of remaining
  // repositories to index.
  if (checkpoint != null) {
    try {
      FullTraversalCheckpoint decodedCheckpoint = FullTraversalCheckpoint
          .fromBytes(checkpoint);
      repositories = decodedCheckpoint.getRemainingRepositories();
    } catch (IOException e) {
      throw new RepositoryException.Builder()
          .setErrorMessage("Unable to deserialize checkpoint")
          .setCause(e)
          .build();
    }
  } else {
    // No previous checkpoint, scan for repositories to index
    // based on the connector configuration.
    try {
      repositories = scanRepositories();
    } catch (IOException e) {
      throw toRepositoryError(e, Optional.of("Unable to scan repositories"));
    }
  }

  if (repositories.isEmpty()) {
    // Nothing left to index. Reset the checkpoint to null so the
    // next full traversal starts from the beginning
    Collection<ApiOperation> empty = Collections.emptyList();
    return new CheckpointCloseableIterableImpl.Builder<>(empty)
        .setCheckpoint((byte[]) null)
        .setHasMore(false)
        .build();
  }

  // Still have more repositories to index. Pop the next repository to
  // index off the list. The remaining repositories make up the next
  // checkpoint.
  String repositoryToIndex = repositories.get(0);
  repositories = repositories.subList(1, repositories.size());

  try {
    log.info(() -> String.format("Traversing repository %s", repositoryToIndex));
    Collection<ApiOperation> items = collectRepositoryItems(repositoryToIndex);
    FullTraversalCheckpoint newCheckpoint = new FullTraversalCheckpoint(repositories);
    return new CheckpointCloseableIterableImpl.Builder<>(items)
        .setHasMore(true)
        .setCheckpoint(newCheckpoint.toBytes())
        .build();
  } catch (IOException e) {
    String errorMessage = String.format("Unable to traverse repo: %s",
        repositoryToIndex);
    throw toRepositoryError(e, Optional.of(errorMessage));
  }
}

メソッド collectRepositoryItems() は、単一の GitHub リポジトリのトラバーサルを処理します。このメソッドは、キューにプッシュされるアイテムを表す ApiOperations のコレクションを返します。アイテムは、リソース名とアイテムの現在の状態を表すハッシュ値としてプッシュされます。

ハッシュ値は、GitHub リポジトリの後続のトラバーサルで使用されます。この値は、追加のコンテンツをアップロードすることなく、コンテンツが変更されたかどうかを判断するための軽量なチェックを提供します。コネクタはすべてのアイテムを盲目的にキューに登録します。アイテムが新しい場合やハッシュ値が変更された場合、キューでポーリングできるようになります。それ以外の場合、アイテムは変更されていないと見なされます。

GithubRepository.java

GitHub で表示

/**
 * Fetch IDs to  push in to the queue for all items in the repository.
 * Currently captures issues & content in the master branch.
 *
 * @param name Name of repository to index
 * @return Items to push into the queue for later indexing
 * @throws IOException if error reading issues
 */
private Collection<ApiOperation> collectRepositoryItems(String name)
    throws IOException {
  List<ApiOperation> operations = new ArrayList<>();
  GHRepository repo = github.getRepository(name);

  // Add the repository as an item to be indexed
  String metadataHash = repo.getUpdatedAt().toString();
  String resourceName = repo.getHtmlUrl().getPath();
  PushItem repositoryPushItem = new PushItem()
      .setMetadataHash(metadataHash);
  PushItems items = new PushItems.Builder()
      .addPushItem(resourceName, repositoryPushItem)
      .build();

  operations.add(items);
  // Add issues/pull requests & files
  operations.add(collectIssues(repo));
  operations.add(collectContent(repo));
  return operations;
}

キューの処理

フル走査が完了すると、コネクタはインデックス登録が必要なアイテムについてキューのポーリングを開始します。getDoc() メソッドは、キューから取得されたアイテムごとに呼び出されます。このメソッドは、GitHub からアイテムを読み取り、インデックス登録に適した表現に変換します。

コネクタは、いつでも変更される可能性があるライブデータに対して実行されるため、getDoc() はキュー内のアイテムがまだ有効であることを確認し、存在しなくなったアイテムをインデックスから削除します。

GithubRepository.java

GitHub で表示

/**
 * Gets a single data repository item and indexes it if required.
 *
 * <p>This method is called by the {@link ListingConnector} during a poll
 * of the Cloud Search queue. Each queued item is processed
 * individually depending on its state in the data repository.
 *
 * @param item the data repository item to retrieve
 * @return the item's state determines which type of
 * {@link ApiOperation} is returned:
 * {@link RepositoryDoc}, {@link DeleteItem}, or {@link PushItem}
 */
@Override
public ApiOperation getDoc(Item item) throws RepositoryException {
  log.info(() -> String.format("Processing item: %s ", item.getName()));
  Object githubObject;
  try {
    // Retrieve the item from GitHub
    githubObject = getGithubObject(item.getName());
    if (githubObject instanceof GHRepository) {
      return indexItem((GHRepository) githubObject, item);
    } else if (githubObject instanceof GHPullRequest) {
      return indexItem((GHPullRequest) githubObject, item);
    } else if (githubObject instanceof GHIssue) {
      return indexItem((GHIssue) githubObject, item);
    } else if (githubObject instanceof GHContent) {
      return indexItem((GHContent) githubObject, item);
    } else {
      String errorMessage = String.format("Unexpected item received: %s",
          item.getName());
      throw new RepositoryException.Builder()
          .setErrorMessage(errorMessage)
          .setErrorType(RepositoryException.ErrorType.UNKNOWN)
          .build();
    }
  } catch (FileNotFoundException e) {
    log.info(() -> String.format("Deleting item: %s ", item.getName()));
    return ApiOperations.deleteItem(item.getName());
  } catch (IOException e) {
    String errorMessage = String.format("Unable to retrieve item: %s",
        item.getName());
    throw toRepositoryError(e, Optional.of(errorMessage));
  }
}

コネクタがインデックス登録する GitHub オブジェクトごとに、対応する indexItem() メソッドが Cloud Search のアイテム表現の構築を処理します。たとえば、コンテンツアイテムの表現を構築するには:

GithubRepository.java

GitHub で表示

/**
 * Build the ApiOperation to index a content item (file).
 *
 * @param content      Content item to index
 * @param previousItem Previous item state in the index
 * @return ApiOperation (RepositoryDoc if indexing,  PushItem if not modified)
 * @throws IOException if unable to create operation
 */
private ApiOperation indexItem(GHContent content, Item previousItem)
    throws IOException {
  String metadataHash = content.getSha();

  // If previously indexed and unchanged, just requeue as unmodified
  if (canSkipIndexing(previousItem, metadataHash)) {
    return notModified(previousItem.getName());
  }

  String resourceName = new URL(content.getHtmlUrl()).getPath();
  FieldOrValue<String> title = FieldOrValue.withValue(content.getName());
  FieldOrValue<String> url = FieldOrValue.withValue(content.getHtmlUrl());

  String containerName = content.getOwner().getHtmlUrl().getPath();
  String programmingLanguage = FileExtensions.getLanguageForFile(content.getName());

  // Structured data based on the schema
  Multimap<String, Object> structuredData = ArrayListMultimap.create();
  structuredData.put("organization", content.getOwner().getOwnerName());
  structuredData.put("repository", content.getOwner().getName());
  structuredData.put("path", content.getPath());
  structuredData.put("language", programmingLanguage);

  Item item = IndexingItemBuilder.fromConfiguration(resourceName)
      .setTitle(title)
      .setContainerName(containerName)
      .setSourceRepositoryUrl(url)
      .setItemType(IndexingItemBuilder.ItemType.CONTAINER_ITEM)
      .setObjectType("file")
      .setValues(structuredData)
      .setVersion(Longs.toByteArray(System.currentTimeMillis()))
      .setHash(content.getSha())
      .build();

  // Index the file content too
  String mimeType = FileTypeMap.getDefaultFileTypeMap()
      .getContentType(content.getName());
  AbstractInputStreamContent fileContent = new InputStreamContent(
      mimeType, content.read())
      .setLength(content.getSize())
      .setCloseInputStream(true);
  return new RepositoryDoc.Builder()
      .setItem(item)
      .setContent(fileContent, IndexingService.ContentFormat.RAW)
      .setRequestMode(IndexingService.RequestMode.SYNCHRONOUS)
      .build();
}

次に、検索インターフェースをデプロイします。

前へ次へ

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

コネクタをビルドする

サービス アカウントの認証情報を作成する

サードパーティのサポートを初期化する

データソースを作成する

GitHub API の個人アクセス トークンを生成する

コネクタを構成する

スキーマを更新する

コネクタを実行する

コードの確認

アプリケーションの起動

GitHub リポジトリのトラバース

キューの処理

コネクタのデプロイ

サービスアカウントの認証情報を作成する

GitHub API の個人アクセストークンを生成する