کانکتور را مستقر کنید

این صفحه از آموزش جستجوی ابری نحوه تنظیم منبع داده و رابط محتوا برای فهرست‌بندی داده‌ها را نشان می‌دهد. برای شروع از ابتدای این آموزش، به آموزش شروع جستجوی ابری مراجعه کنید.

کانکتور را بسازید

دایرکتوری کاری خود را به دایرکتوری cloud-search-samples/end-to-end/connector تغییر دهید و این دستور را اجرا کنید:

mvn package -DskipTests

این دستور، وابستگی‌های مورد نیاز برای ساخت رابط محتوا را دانلود کرده و کد را کامپایل می‌کند.

ایجاد اعتبارنامه حساب سرویس

این رابط برای فراخوانی APIهای جستجوی ابری به اعتبارنامه‌های حساب سرویس نیاز دارد. برای ایجاد اعتبارنامه‌ها:

  1. به کنسول گوگل کلود برگردید.
  2. در منوی سمت چپ، روی «اعتبارنامه‌ها » کلیک کنید. صفحه «اعتبارنامه‌ها» ظاهر می‌شود.
  3. روی فهرست کشویی + CREATE CREDENTIALS کلیک کنید و Service account را انتخاب کنید. صفحه "Create service account" ظاهر می‌شود.
  4. در فیلد نام حساب سرویس ، عبارت «tutorial» را وارد کنید.
  5. به مقدار شناسه حساب سرویس (درست بعد از نام حساب سرویس) توجه کنید. این مقدار بعداً استفاده خواهد شد.
  6. روی «ایجاد» کلیک کنید. کادر محاوره‌ای «مجوزهای حساب سرویس (اختیاری)» ظاهر می‌شود.
  7. روی ادامه کلیک کنید. کادر محاوره‌ای «اعطای دسترسی کاربران به این حساب سرویس (اختیاری)» ظاهر می‌شود.
  8. روی «انجام شد» کلیک کنید. صفحه «اعتبارنامه‌ها» ظاهر می‌شود.
  9. در قسمت حساب‌های سرویس، روی ایمیل حساب سرویس کلیک کنید. صفحه «جزئیات حساب سرویس» ظاهر می‌شود.
  10. در قسمت کلیدها، روی فهرست کشویی «افزودن کلید» کلیک کنید و «ایجاد کلید جدید » را انتخاب کنید. کادر محاوره‌ای «ایجاد کلید خصوصی» ظاهر می‌شود.
  11. روی ایجاد کلیک کنید.
  12. (اختیاری) اگر کادر محاوره‌ای «آیا می‌خواهید دانلودها در console.cloud.google.com مجاز باشند؟» ظاهر شد، روی «مجاز کردن» کلیک کنید.
  13. یک فایل کلید خصوصی در رایانه شما ذخیره می‌شود. به محل فایل دانلود شده توجه کنید. این فایل برای پیکربندی رابط محتوا استفاده می‌شود تا بتواند هنگام فراخوانی APIهای جستجوی ابری گوگل، خود را احراز هویت کند.

پشتیبانی شخص ثالث را راه‌اندازی کنید

قبل از اینکه بتوانید هرگونه API جستجوی ابری دیگری را فراخوانی کنید، باید پشتیبانی شخص ثالث را برای جستجوی ابری گوگل راه‌اندازی کنید.

برای راه‌اندازی اولیه پشتیبانی شخص ثالث برای جستجوی ابری:

  1. پروژه پلتفرم جستجوی ابری شما شامل اعتبارنامه‌های حساب سرویس است. با این حال، برای راه‌اندازی اولیه پشتیبانی شخص ثالث، باید اعتبارنامه‌های برنامه وب را ایجاد کنید. برای دستورالعمل‌های مربوط به نحوه ایجاد اعتبارنامه‌های برنامه وب، به ایجاد اعتبارنامه‌ها مراجعه کنید. پس از تکمیل این مرحله، باید یک شناسه کلاینت و فایل مخفی کلاینت داشته باشید.

  2. برای دریافت توکن دسترسی از محیط OAuth 2 گوگل استفاده کنید:

    1. روی تنظیمات کلیک کنید و اعتبارنامه‌های احراز هویت خودتان را بررسی کنید.
    2. شناسه کلاینت و رمز کلاینت را از مرحله ۱ وارد کنید.
    3. روی بستن کلیک کنید.
    4. در فیلد scopes، عبارت https://www.googleapis.com/auth/cloud_search.settings را تایپ کنید و روی Authorize کلیک کنید. محیط OAuth 2 یک کد مجوز برمی‌گرداند.
    5. برای توکن‌ها روی کد مجوز اکسچنج کلیک کنید. یک توکن برگردانده می‌شود.
  3. برای راه‌اندازی اولیه پشتیبانی شخص ثالث برای جستجوی ابری، از دستور curl زیر استفاده کنید. حتماً [YOUR_ACCESS_TOKEN] را با توکنی که در مرحله 2 به دست آمده است، جایگزین کنید.

    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 است. برای مثال:

    {
    name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY"
    }
    

    در صورت عدم موفقیت، با پشتیبانی Cloud Search تماس بگیرید.

  4. برای تأیید اینکه پشتیبانی شخص ثالث راه‌اندازی شده است، از operations.get استفاده کنید:

    curl \
    'https://cloudsearch.googleapis.com/v1/operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY?key=
    [YOUR_API_KEY]' \
    --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
    --header 'Accept: application/json' \
    --compressed
    

    وقتی مقداردهی اولیه شخص ثالث کامل شد، شامل فیلد done می‌شود که روی true تنظیم شده است. برای مثال:

    {
    name: "operations/customers/01b3fqdm/lro/AOIL6eBv7fEfiZ_hUSpm8KQDt1Mnd6dj5Ru3MXf-jri4xK6Pyb2-Lwfn8vQKg74pgxlxjrY"
    done: true
    }
    

منبع داده را ایجاد کنید

در مرحله بعد، یک منبع داده در کنسول مدیریت ایجاد کنید. منبع داده یک فضای نام برای فهرست‌بندی محتوا با استفاده از کانکتور فراهم می‌کند.

  1. کنسول مدیریت گوگل را باز کنید.
  2. روی آیکون برنامه‌ها کلیک کنید. صفحه «مدیریت برنامه‌ها» ظاهر می‌شود.
  3. روی Google Workspace کلیک کنید. صفحه "Apps Google Workspace administration" نمایش داده می‌شود.
  4. به پایین اسکرول کنید و روی Cloud Search کلیک کنید. صفحه «تنظیمات Google Workspace» نمایش داده می‌شود.
  5. روی منابع داده شخص ثالث کلیک کنید. صفحه «منابع داده» ظاهر می‌شود.
  6. روی علامت + زرد دایره‌ای شکل کلیک کنید. کادر محاوره‌ای «افزودن منبع داده جدید» ظاهر می‌شود.
  7. در فیلد نام نمایشی ، عبارت «tutorial» را تایپ کنید.
  8. در فیلد آدرس‌های ایمیل حساب سرویس ، آدرس ایمیل حساب سرویسی که در بخش قبل ایجاد کرده‌اید را وارد کنید. اگر آدرس ایمیل حساب سرویس را نمی‌دانید، مقدار آن را در صفحه حساب‌های سرویس جستجو کنید.
  9. روی افزودن کلیک کنید. کادر محاوره‌ای «منبع داده با موفقیت ایجاد شد» ظاهر می‌شود.
  10. روی * تأیید کلیک کنید. شناسه منبع منبع داده تازه ایجاد شده را یادداشت کنید. شناسه منبع برای پیکربندی رابط محتوا استفاده می‌شود.

یک توکن دسترسی شخصی برای API گیت‌هاب ایجاد کنید

این رابط برای داشتن سهمیه کافی، نیاز به دسترسی احراز هویت شده به API گیت‌هاب دارد. برای سادگی، رابط به جای OAuth از توکن‌های دسترسی شخصی استفاده می‌کند. توکن‌های شخصی امکان احراز هویت به عنوان یک کاربر با مجموعه‌ای محدود از مجوزها، مشابه OAuth، را فراهم می‌کنند.

  1. وارد گیت‌هاب شوید.
  2. در گوشه بالا سمت راست، روی تصویر پروفایل خود کلیک کنید. یک منوی کشویی ظاهر می‌شود.
  3. روی تنظیمات کلیک کنید.
  4. روی تنظیمات توسعه‌دهنده کلیک کنید.
  5. روی نشانه‌های دسترسی شخصی کلیک کنید.
  6. روی ایجاد توکن دسترسی شخصی کلیک کنید.
  7. در قسمت یادداشت ، عبارت «آموزش جستجوی ابری» را وارد کنید.
  8. دامنه public_repo را بررسی کنید.
  9. روی ایجاد توکن کلیک کنید.
  10. به توکن تولید شده توجه کنید. این توکن توسط کانکتور برای فراخوانی APIهای گیت‌هاب استفاده می‌شود و سهمیه API را برای انجام ایندکس‌گذاری فراهم می‌کند.

پیکربندی کانکتور

پس از ایجاد اعتبارنامه‌ها و منبع داده، پیکربندی کانکتور را به‌روزرسانی کنید تا این مقادیر را شامل شود:

  1. از خط فرمان، دایرکتوری را به cloud-search-samples/end-to-end/connector/ تغییر دهید.
  2. فایل sample-config.properties را با یک ویرایشگر متن باز کنید.
  3. پارامتر api.serviceAccountPrivateKeyFile را روی مسیر فایل اعتبارنامه‌های سرویسی که قبلاً دانلود کرده‌اید، تنظیم کنید.
  4. پارامتر api.sourceId را برابر با شناسه منبع داده‌ای که قبلاً ایجاد کرده‌اید، تنظیم کنید.
  5. پارامتر github.user را روی نام کاربری GitHub خود تنظیم کنید.
  6. پارامتر github.token را روی توکن دسترسی که قبلاً ایجاد کرده‌اید، تنظیم کنید.
  7. فایل را ذخیره کنید.

طرحواره را به‌روزرسانی کنید

این رابط، محتوای ساختاریافته و بدون ساختار را فهرست‌بندی می‌کند. قبل از فهرست‌بندی داده‌ها، باید طرحواره منبع داده را به‌روزرسانی کنید. دستور زیر را برای به‌روزرسانی طرحواره اجرا کنید:

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 است. ایندکس کردن مخزن حدود ۱ دقیقه طول می‌کشد. پس از ایندکس اولیه، کانکتور به نظرسنجی برای یافتن تغییرات مخزن که باید در فهرست جستجوی ابری منعکس شوند، ادامه می‌دهد.

بررسی کد

بخش‌های باقی‌مانده نحوه ساخت کانکتور را بررسی می‌کنند.

شروع برنامه

نقطه ورود به کانکتور، کلاس GithubConnector است. متد main ، نمونه‌ای از IndexingApplication مربوط به SDK ایجاد کرده و آن را اجرا می‌کند.

GithubConnector.java
/**
 * 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();
}

ListingConnector ارائه شده توسط SDK یک استراتژی پیمایش را پیاده‌سازی می‌کند که از صف‌های جستجوی ابری برای ردیابی وضعیت اقلام در فهرست استفاده می‌کند. این ابزار برای دسترسی به محتوا از GithubRepository که توسط رابط نمونه پیاده‌سازی شده است، استفاده می‌کند.

پیمایش مخازن گیت‌هاب

در طول پیمایش‌های کامل، متد getIds() فراخوانی می‌شود تا مواردی را که ممکن است نیاز به اندیس‌گذاری در صف داشته باشند، وارد صف کند.

این رابط می‌تواند چندین مخزن یا سازمان را فهرست‌بندی کند. برای به حداقل رساندن تأثیر یک شکست، یک مخزن GitHub در یک زمان پیمایش می‌شود. یک نقطه بررسی با نتایج پیمایش که شامل لیست مخازنی است که باید در فراخوانی‌های بعدی getIds() فهرست‌بندی شوند، بازگردانده می‌شود. در صورت بروز خطا، فهرست‌بندی به جای شروع از ابتدا، در مخزن فعلی از سر گرفته می‌شود.

مخزن گیت‌هاب.جاوا
/**
 * 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 استفاده می‌شود. این مقدار، بررسی سبکی را برای تعیین اینکه آیا محتوا تغییر کرده است یا خیر، بدون نیاز به آپلود محتوای اضافی، فراهم می‌کند. کانکتور به طور کورکورانه همه موارد را در صف قرار می‌دهد. اگر مورد جدید باشد یا مقدار هش تغییر کرده باشد، برای نظرسنجی در صف در دسترس قرار می‌گیرد. در غیر این صورت، مورد اصلاح نشده در نظر گرفته می‌شود.

مخزن گیت‌هاب.جاوا
/**
 * 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() همچنین تأیید می‌کند که آیتم موجود در صف هنوز معتبر است و هر آیتمی را از ایندکس که دیگر وجود ندارد حذف می‌کند.

مخزن گیت‌هاب.جاوا
/**
 * 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));
  }
}

برای هر یک از اشیاء گیت‌هابِ اندیس‌های رابط، متد indexItem() مربوطه، ساخت نمایش آیتم برای جستجوی ابری را مدیریت می‌کند. به عنوان مثال، برای ساخت نمایش آیتم‌های محتوا:

مخزن گیت‌هاب.جاوا
/**
 * 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();
}

در مرحله بعد، رابط جستجو را مستقر کنید.

قبلی بعدی