یک اتصال دهنده محتوا ایجاد کنید

رابط محتوا یک برنامه نرم‌افزاری است که داده‌ها را در یک مخزن سازمانی پیمایش می‌کند و یک منبع داده را پر می‌کند. گوگل گزینه‌های زیر را برای توسعه رابط‌های محتوا ارائه می‌دهد:

  • کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK). این گزینه خوبی برای برنامه‌نویسان جاوا است. SDK یک پوشش پیرامون REST API است که به شما امکان می‌دهد به سرعت رابط‌ها را ایجاد کنید. برای ایجاد یک رابط محتوا با استفاده از SDK، به بخش «ایجاد یک رابط محتوا با استفاده از SDK رابط محتوا» مراجعه کنید.

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

یک رابط محتوای معمولی وظایف زیر را انجام می‌دهد:

  1. پارامترهای پیکربندی را می‌خواند و پردازش می‌کند.
  2. تکه‌های گسسته از داده‌های قابل فهرست‌بندی، به نام " آیتم‌ها "، را از مخزن شخص ثالث دریافت می‌کند.
  3. ACLها، فراداده‌ها و داده‌های محتوا را در آیتم‌های قابل فهرست‌بندی ترکیب می‌کند.
  4. آیتم‌ها را در منبع داده Cloud Search فهرست‌بندی می‌کند.
  5. (اختیاری) به اعلان‌های تغییر از مخزن گوش می‌دهد. اعلان‌های تغییر به درخواست‌های نمایه‌سازی تبدیل می‌شوند تا منبع داده Cloud Search را همگام نگه دارند. رابط فقط در صورتی این کار را انجام می‌دهد که مخزن از تشخیص تغییر پشتیبانی کند.

با استفاده از کیت توسعه نرم‌افزاری رابط محتوا (Content Connector SDK)، یک رابط محتوا (content connector) ایجاد کنید.

بخش‌های زیر نحوه ایجاد یک رابط محتوا با استفاده از کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK) را توضیح می‌دهند.

وابستگی‌ها را تنظیم کنید

این وابستگی‌ها را در فایل ساخت خود لحاظ کنید.

ماون

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

گرادل

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

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

هر کانکتور از یک فایل پیکربندی برای پارامترهایی مانند شناسه مخزن شما استفاده می‌کند. پارامترها را به صورت جفت‌های کلید-مقدار تعریف کنید، مانند api.sourceId= 1234567890abcdef .

کیت توسعه نرم‌افزار جستجوی ابری گوگل (Google Cloud Search SDK) شامل پارامترهای ارائه شده توسط گوگل برای همه کانکتورها است. شما باید موارد زیر را در فایل پیکربندی خود اعلام کنید:

  • رابط محتوا : api.sourceId و api.serviceAccountPrivateKeyFile را تعریف کنید. این‌ها مخزن شما و کلید خصوصی مورد نیاز برای دسترسی را مشخص می‌کنند.
  • رابط هویت : برای شناسایی منبع هویت خارجی خود، api.identitySourceId را تعریف کنید. برای همگام‌سازی کاربر، api.customerId (شناسه منحصر به فرد برای حساب Google Workspace شما) را نیز تعریف کنید.

پارامترهای ارائه شده توسط گوگل را فقط طوری تعریف کنید که مقادیر پیش‌فرض آنها لغو شود. برای جزئیات بیشتر در مورد تولید شناسه‌ها و کلیدها، به پارامترهای ارائه شده توسط گوگل مراجعه کنید.

همچنین می‌توانید پارامترهای مختص مخزن را در فایل پیکربندی خود تعریف کنید.

فایل پیکربندی را به کانکتور ارسال کنید

ویژگی سیستم config را برای ارسال فایل پیکربندی تنظیم کنید. هنگام شروع اتصال از آرگومان -D استفاده کنید. به عنوان مثال:

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

اگر این آرگومان را حذف کنید، SDK تلاش می‌کند از فایلی با نام connector-config.properties در دایرکتوری محلی استفاده کند.

استراتژی پیمایش خود را تعیین کنید

وظیفه اصلی یک رابط محتوا، پیمایش یک مخزن و فهرست‌بندی داده‌های آن است. شما باید بر اساس اندازه و طرح مخزن خود، یک استراتژی پیاده‌سازی کنید. می‌توانید استراتژی خودتان را طراحی کنید یا یک استراتژی از SDK انتخاب کنید:

استراتژی پیمایش کامل
کل مخزن را اسکن کرده و هر مورد را فهرست‌بندی می‌کند. این استراتژی برای مخازن کوچکی که می‌توانید سربار یک پیمایش کامل را در طول هر فهرست‌بندی تحمل کنید، بهترین گزینه است. از آن برای مخازن کوچکی که عمدتاً داده‌های ایستا و غیرسلسله مراتبی دارند یا زمانی که تشخیص تغییر دشوار است، استفاده کنید.
استراتژی پیمایش لیست
کل مخزن را برای تعیین وضعیت هر مورد اسکن می‌کند، سپس فقط موارد جدید یا به‌روزرسانی‌شده را فهرست‌بندی می‌کند. از این برای به‌روزرسانی‌های افزایشی یک فهرست بزرگ و غیرسلسله مراتبی، زمانی که تشخیص تغییر پشتیبانی نمی‌شود، استفاده کنید.
پیمایش گراف
یک گره والد را برای تعیین وضعیت آیتم‌های آن اسکن می‌کند، سپس آیتم‌های جدید یا به‌روزرسانی‌شده را در آن گره فهرست‌بندی می‌کند. سپس به صورت بازگشتی گره‌های فرزند را پردازش می‌کند. از این برای مخازن سلسله مراتبی که فهرست کردن همه شناسه‌ها عملی نیست، مانند ساختارهای دایرکتوری یا وب‌سایت‌ها، استفاده کنید.

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

با استفاده از یک کلاس الگو، یک رابط پیمایش کامل ایجاد کنید

این بخش به کدی از FullTraversalSample اشاره دارد.

نقطه ورود کانکتور را پیاده‌سازی کنید

نقطه ورود، متد main() است. این متد یک نمونه Application ایجاد می‌کند و start() را برای اجرای کانکتور فراخوانی می‌کند.

قبل از فراخوانی application.start() ، از کلاس IndexingApplication.Builder برای نمونه‌سازی الگوی FullTraversalConnector استفاده کنید. این الگو یک شیء Repository می‌پذیرد.

نمونه پیمایش کامل.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @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 SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

SDK پس از فراخوانی Application.build() ) توسط متد main() شما، تابع initConfig() () را فراخوانی می‌کند. متد initConfig() به صورت زیر است:

  1. اطمینان حاصل می‌کند که Configuration از قبل مقداردهی اولیه نشده است.
  2. شیء Configuration را با جفت‌های کلید-مقدار ارائه شده توسط گوگل، مقداردهی اولیه می‌کند.

پیاده‌سازی رابط مخزن (Repository)

شیء Repository آیتم‌های مخزن را پیمایش و فهرست‌بندی می‌کند. هنگام استفاده از یک الگو، فقط باید متدهای خاصی را در رابط Repository بازنویسی کنید. برای FullTraversalConnector ، بازنویسی کنید:

  • init() : برای تنظیم و مقداردهی اولیه مخزن.
  • getAllDocs() : برای پیمایش و فهرست‌بندی همه آیتم‌ها. این متد برای هر پیمایش زمان‌بندی‌شده یک بار فراخوانی می‌شود.
  • (اختیاری) getChanges() : اگر مخزن شما از تشخیص تغییر پشتیبانی می‌کند، این را برای بازیابی و فهرست‌بندی موارد تغییر یافته بازنویسی کنید.
  • (اختیاری) close() : برای پاکسازی مخزن در هنگام خاموش شدن سیستم.

هر متد یک شیء ApiOperation برمی‌گرداند که با استفاده از IndexingService.indexItem() ایندکس‌گذاری را انجام می‌دهد.

دریافت پارامترهای پیکربندی سفارشی

برای مدیریت پیکربندی کانکتور خود، باید هرگونه پارامتر سفارشی را از شیء Configuration بازیابی کنید. این کار را در متد init() کلاس Repository خود انجام دهید.

کلاس Configuration شامل متدهایی برای بازیابی انواع مختلف داده است. هر متد یک شیء ConfigValue را برمی‌گرداند. از متد get() شیء ConfigValue برای بازیابی مقدار استفاده کنید. این قطعه کد از FullTraversalSample نحوه بازیابی یک مقدار صحیح سفارشی را نشان می‌دهد:

نمونه پیمایش کامل.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

برای بازیابی و تجزیه پارامترهایی با چندین مقدار، از یکی از تجزیه‌کننده‌های نوع کلاس Configuration استفاده کنید. این قطعه کد از رابط آموزشی از getMultiValue برای بازیابی لیستی از نام‌های مخزن GitHub استفاده می‌کند:

مخزن گیت‌هاب.جاوا
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

انجام پیمایش کامل

برای انجام یک پیمایش کامل، تابع getAllDocs() را نادیده می‌گیرد. این متد یک نقطه‌ی بررسی می‌پذیرد تا در صورت قطع شدن، اندیس‌گذاری را از سر بگیرد. برای هر آیتم:

  1. مجوزها را تنظیم کنید.
  2. تنظیم فراداده (metadata).
  3. آنها را در یک RepositoryDoc ترکیب کنید.
  4. هر آیتم را در تکرارکننده‌ای که توسط getAllDocs() برگردانده می‌شود، بسته‌بندی کنید.

اگر مجموعه اقلام برای یک فراخوانی خیلی بزرگ است، از یک Checkpoint استفاده کنید و تابع hasMore(true) را فراخوانی کنید.

تنظیم مجوزها برای یک مورد

مخازن از لیست‌های کنترل دسترسی (ACL) برای شناسایی کاربران یا گروه‌هایی که به یک مورد دسترسی دارند استفاده می‌کنند. یک ACL، شناسه‌های کاربران یا گروه‌های مجاز را فهرست می‌کند.

برای اطمینان از اینکه کاربران فقط نتایج جستجویی را که مجاز به دسترسی به آنها هستند، مشاهده می‌کنند، باید ACL های مخزن خود را تکثیر کنید. هنگام فهرست‌بندی یک مورد، ACL را نیز لحاظ کنید تا Google Cloud Search بتواند سطح دسترسی صحیح را ارائه دهد.

کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK) شامل کلاس‌ها و روش‌هایی برای مدل‌سازی ACLهای اکثر مخازن است. ACLهای مخزن خود را تجزیه و تحلیل کنید و ACLهای مربوطه را برای جستجوی ابری (Cloud Search) در حین فهرست‌بندی ایجاد کنید. مدل‌سازی ACLهای پیچیده، مانند آن‌هایی که از وراثت استفاده می‌کنند، نیاز به برنامه‌ریزی دقیق دارد. برای اطلاعات بیشتر، به ACLهای جستجوی ابری (Cloud Search ACLs) مراجعه کنید.

از کلاس Acl.Builder برای تنظیم دسترسی استفاده کنید. این قطعه کد از نمونه کامل پیمایش به همه کاربران دامنه ( getCustomerPrincipal() ) اجازه می‌دهد همه موارد ( setReaders() ) را بخوانند:

نمونه پیمایش کامل.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

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

تنظیم فراداده برای یک آیتم

متادیتا در یک شیء Item ذخیره می‌شود. برای ایجاد یک Item ، به یک شناسه منحصر به فرد، نوع آیتم، ACL، URL و نسخه نیاز دارید. از کلاس کمکی IndexingItemBuilder استفاده کنید.

نمونه پیمایش کامل.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();
ایجاد آیتم قابل فهرست‌بندی

از کلاس RepositoryDoc.Builder استفاده کنید.

نمونه پیمایش کامل.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

یک RepositoryDoc یک ApiOperation است که درخواست IndexingService.indexItem() را انجام می‌دهد.

از متد setRequestMode() از کلاس RepositoryDoc.Builder برای تنظیم درخواست ایندکس‌گذاری روی ASYNCHRONOUS یا SYNCHRONOUS استفاده کنید:

ASYNCHRONOUS
این حالت تأخیر بیشتری در اندیس‌گذاری تا ارائه سرویس دارد اما سهمیه توان عملیاتی بیشتری را در خود جای می‌دهد. از حالت ناهمزمان برای اندیس‌گذاری اولیه (backfill) کل مخزن استفاده کنید.
SYNCHRONOUS
این حالت تأخیر کمتری در اندیس‌گذاری تا ارائه سرویس دارد، اما سهمیه توان عملیاتی کمتری دارد. از حالت همگام برای اندیس‌گذاری به‌روزرسانی‌ها و تغییرات مخزن استفاده کنید. در صورت عدم تعیین، حالت درخواست به صورت پیش‌فرض روی SYNCHRONOUS تنظیم می‌شود.
هر آیتم قابل فهرست‌بندی را در یک تکرارکننده بسته‌بندی کنید

متد getAllDocs() یک CheckpointCloseableIterable از اشیاء RepositoryDoc برمی‌گرداند. از کلاس CheckpointCloseableIterableImpl.Builder استفاده کنید.

نمونه پیمایش کامل.java
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

مراحل بعدی

با استفاده از یک کلاس الگو، یک رابط پیمایش لیست ایجاد کنید

صف نمایه‌سازی جستجوی ابری، شناسه‌ها و هش‌های اختیاری را برای اقلام مخزن نگه می‌دارد. یک رابط پیمایش لیست، شناسه‌ها را به این صف ارسال کرده و آنها را برای نمایه‌سازی بازیابی می‌کند. جستجوی ابری این صف‌ها را برای تعیین وضعیت اقلام، مانند حذف‌ها، نگهداری می‌کند. به صف نمایه‌سازی جستجوی ابری مراجعه کنید.

این بخش به ListTraversalSample اشاره دارد.

نقطه ورود کانکتور را پیاده‌سازی کنید

متد main() یک نمونه Application ایجاد می‌کند و start() را فراخوانی می‌کند. IndexingApplication.Builder برای نمونه‌سازی الگوی ListingConnector استفاده کنید.

نمونه پیمایش لیست.جاوا
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @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 SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

پیاده‌سازی رابط مخزن (Repository)

متدهای زیر را برای ListingConnector بازنویسی کنید:

  • init() : برای تنظیم مخزن.
  • getIds() : برای بازیابی شناسه‌ها و هش‌ها برای همه رکوردها.
  • getDoc() : برای اضافه کردن، به‌روزرسانی یا حذف آیتم‌ها از ایندکس.
  • (اختیاری) getChanges() : برای به‌روزرسانی‌های افزایشی با استفاده از تشخیص تغییر.
  • (اختیاری) close() : برای پاکسازی مخزن.

پیمایش لیست را انجام دهید

برای بازیابی شناسه‌ها و هش‌ها، تابع getIds() را بازنویسی کنید. برای مدیریت هر آیتم در صف نمایه‌سازی جستجوی ابری، تابع getDoc() را بازنویسی کنید.

شناسه‌های آیتم و مقادیر هش را فشار دهید

برای دریافت شناسه‌ها و هش‌های محتوا، getIds() را بازنویسی کنید. آن‌ها را در یک درخواست PushItems به صف نمایه‌سازی بسته‌بندی کنید.

نمونه پیمایش لیست.جاوا
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

از PushItems.Builder برای بسته‌بندی شناسه‌ها و هش‌ها استفاده کنید.

نمونه پیمایش لیست.جاوا
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;
بازیابی و مدیریت هر مورد

برای مدیریت آیتم‌های موجود در صف فهرست‌بندی، getDoc() را بازنویسی کنید. آیتم‌ها می‌توانند جدید، اصلاح‌شده، بدون تغییر یا حذف‌شده باشند.

  1. بررسی کنید که آیا شناسه‌ی آیتم در مخزن وجود دارد یا خیر. اگر نه، آن را حذف کنید.
  2. وضعیت را از شاخص نظرسنجی کنید. اگر تغییر نکرده ( ACCEPTED )، هیچ کاری انجام ندهید.
  3. فهرست کردن موارد تغییر یافته یا جدید: تنظیم مجوزها، تنظیم فراداده، ترکیب در یک RepositoryDoc و بازگرداندن آن.
رسیدگی به موارد حذف شده

این قطعه کد نشان می‌دهد که چگونه می‌توان وجود یک آیتم را تشخیص داد و در صورت عدم وجود، آن را حذف کرد.

نمونه پیمایش لیست.جاوا
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}
رسیدگی به موارد بدون تغییر

برای مدیریت موارد بدون تغییر، صف فهرست‌بندی را بررسی کنید.

نمونه پیمایش لیست.جاوا
String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

این مثال از یک هش برای تشخیص تغییرات استفاده می‌کند.

نمونه پیمایش لیست.جاوا
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}
تنظیم مجوزها برای یک مورد

مخازن از لیست‌های کنترل دسترسی (ACL) برای شناسایی کاربران یا گروه‌هایی که به یک مورد دسترسی دارند استفاده می‌کنند. یک ACL، شناسه‌های کاربران یا گروه‌های مجاز را فهرست می‌کند.

برای اطمینان از اینکه کاربران فقط نتایج جستجویی را که مجاز به دسترسی به آنها هستند، مشاهده می‌کنند، باید ACL های مخزن خود را تکثیر کنید. هنگام فهرست‌بندی یک مورد، ACL را نیز لحاظ کنید تا Google Cloud Search بتواند سطح دسترسی صحیح را ارائه دهد.

کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK) شامل کلاس‌ها و روش‌هایی برای مدل‌سازی ACLهای اکثر مخازن است. ACLهای مخزن خود را تجزیه و تحلیل کنید و ACLهای مربوطه را برای جستجوی ابری (Cloud Search) در حین فهرست‌بندی ایجاد کنید. مدل‌سازی ACLهای پیچیده، مانند آن‌هایی که از وراثت استفاده می‌کنند، نیاز به برنامه‌ریزی دقیق دارد. برای اطلاعات بیشتر، به ACLهای جستجوی ابری (Cloud Search ACLs) مراجعه کنید.

از کلاس Acl.Builder برای تنظیم دسترسی استفاده کنید. این قطعه کد از نمونه کامل پیمایش به همه کاربران دامنه ( getCustomerPrincipal() ) اجازه می‌دهد همه موارد ( setReaders() ) را بخوانند:

نمونه پیمایش کامل.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

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

تنظیم فراداده برای یک آیتم
نمونه پیمایش لیست.جاوا
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();
ایجاد یک آیتم قابل فهرست‌بندی
نمونه پیمایش لیست.جاوا
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

از متد setRequestMode() از کلاس RepositoryDoc.Builder برای تنظیم درخواست ایندکس‌گذاری روی ASYNCHRONOUS یا SYNCHRONOUS استفاده کنید:

ASYNCHRONOUS
این حالت تأخیر بیشتری در اندیس‌گذاری تا ارائه سرویس دارد اما سهمیه توان عملیاتی بیشتری را در خود جای می‌دهد. از حالت ناهمزمان برای اندیس‌گذاری اولیه (backfill) کل مخزن استفاده کنید.
SYNCHRONOUS
این حالت تأخیر کمتری در اندیس‌گذاری تا ارائه سرویس دارد، اما سهمیه توان عملیاتی کمتری دارد. از حالت همگام برای اندیس‌گذاری به‌روزرسانی‌ها و تغییرات مخزن استفاده کنید. در صورت عدم تعیین، حالت درخواست به صورت پیش‌فرض روی SYNCHRONOUS تنظیم می‌شود.

مراحل بعدی

در اینجا چند گام بعدی که می‌توانید بردارید، آورده شده است:

ایجاد یک رابط پیمایش گراف با استفاده از یک کلاس الگو

صف نمایه‌سازی جستجوی ابری، شناسه‌ها و مقادیر هش اختیاری را برای هر مورد در مخزن نگه می‌دارد. یک رابط پیمایش گراف، شناسه‌های مورد را به صف نمایه‌سازی جستجوی ابری گوگل ارسال می‌کند و آنها را یکی یکی برای نمایه‌سازی بازیابی می‌کند. جستجوی ابری گوگل، صف‌ها را نگهداری می‌کند و محتوای صف را برای تعیین وضعیت مورد، مانند اینکه آیا یک مورد از مخزن حذف شده است یا خیر، مقایسه می‌کند. برای اطلاعات بیشتر در مورد صف نمایه‌سازی جستجوی ابری، به صف نمایه‌سازی جستجوی ابری گوگل مراجعه کنید.

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

نقطه ورود کانکتور را پیاده‌سازی کنید

نقطه ورود به یک کانکتور، متد main() است. این متد یک نمونه از کلاس Application ایجاد می‌کند و متد start() آن را برای اجرای کانکتور فراخوانی می‌کند.

قبل از فراخوانی application.start() ، از کلاس IndexingApplication.Builder برای نمونه‌سازی الگوی ListingConnector استفاده کنید. ListingConnector یک شیء Repository را می‌پذیرد که متدهای آن را پیاده‌سازی می‌کنید.

پیاده‌سازی رابط مخزن (Repository)

init() ، getIds() ، getDoc() و به صورت اختیاری getChanges() یا close() را نادیده بگیرید.

پیمایش گراف را انجام دهید

برای بازیابی شناسه‌های اولیه، getIds() و برای مدیریت آیتم‌ها و ارسال شناسه‌های فرزند به صف getDoc() را نادیده بگیرید.

شناسه‌های آیتم و مقادیر هش را فشار دهید
GraphTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);
بازیابی و مدیریت هر مورد
  1. بررسی کنید که آیا شناسه در مخزن وجود دارد یا خیر. اگر نه، آیتم را حذف کنید.
  2. برای موارد موجود، مجوزها و فراداده‌ها را تنظیم کنید و آنها را در یک RepositoryDoc ترکیب کنید.
  3. شناسه‌های فرزند را به صف نمایه‌سازی ارسال کنید.
  4. RepositoryDoc را برگردانید.
رسیدگی به موارد حذف شده
GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);
تنظیم فراداده و ایجاد آیتم
GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();
GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);
قرار دادن شناسه‌های فرزند در صف فهرست‌بندی
GraphTraversalSample.java
// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

ایجاد یک رابط محتوا با استفاده از REST API

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

استراتژی پیمایش خود را تعیین کنید

استراتژی‌ها (کامل، فهرست و نمودار) از نظر مفهومی مشابه SDK هستند. استراتژی انتخابی خود را با استفاده از REST API پیاده‌سازی کنید.

استراتژی پیمایش و فهرست‌بندی آیتم‌های خود را پیاده‌سازی کنید

طرحواره خود را ثبت کنید، سپس با استفاده از موارد زیر، فهرست را پر کنید:

  1. (اختیاری) items.upload برای فایل‌های بزرگتر از ۱۰۰ کیلوبایت.
  2. (اختیاری) media.upload برای فایل‌های رسانه‌ای.

  3. items.index برای فهرست‌بندی آیتم.

    نمونه درخواست ایندکس گذاری: 

    {
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "viewUrl": "http://www.imdb.com/title/tt2234155/",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": { "values": ["Titanic"] }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love...",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

  4. (اختیاری) برای تأیید نمایه‌سازی از items.get استفاده کنید.

مدیریت تغییرات مخزن

به صورت دوره‌ای کل مخزن را برای فهرست‌بندی کامل، مجدداً فهرست‌بندی کنید. برای پیمایش لیست یا نمودار، از صف فهرست‌بندی Google Cloud برای ردیابی تغییرات استفاده کنید و فقط موارد تغییر یافته را فهرست‌بندی کنید. items.push برای افزودن موارد به صف استفاده کنید.

،

رابط محتوا یک برنامه نرم‌افزاری است که داده‌ها را در یک مخزن سازمانی پیمایش می‌کند و یک منبع داده را پر می‌کند. گوگل گزینه‌های زیر را برای توسعه رابط‌های محتوا ارائه می‌دهد:

  • کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK). این گزینه خوبی برای برنامه‌نویسان جاوا است. SDK یک پوشش پیرامون REST API است که به شما امکان می‌دهد به سرعت رابط‌ها را ایجاد کنید. برای ایجاد یک رابط محتوا با استفاده از SDK، به بخش «ایجاد یک رابط محتوا با استفاده از SDK رابط محتوا» مراجعه کنید.

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

یک رابط محتوای معمولی وظایف زیر را انجام می‌دهد:

  1. پارامترهای پیکربندی را می‌خواند و پردازش می‌کند.
  2. تکه‌های گسسته از داده‌های قابل فهرست‌بندی، به نام " آیتم‌ها "، را از مخزن شخص ثالث دریافت می‌کند.
  3. ACLها، فراداده‌ها و داده‌های محتوا را در آیتم‌های قابل فهرست‌بندی ترکیب می‌کند.
  4. آیتم‌ها را در منبع داده Cloud Search فهرست‌بندی می‌کند.
  5. (اختیاری) به اعلان‌های تغییر از مخزن گوش می‌دهد. اعلان‌های تغییر به درخواست‌های نمایه‌سازی تبدیل می‌شوند تا منبع داده Cloud Search را همگام نگه دارند. رابط فقط در صورتی این کار را انجام می‌دهد که مخزن از تشخیص تغییر پشتیبانی کند.

با استفاده از کیت توسعه نرم‌افزاری رابط محتوا (Content Connector SDK)، یک رابط محتوا (content connector) ایجاد کنید.

بخش‌های زیر نحوه ایجاد یک رابط محتوا با استفاده از کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK) را توضیح می‌دهند.

وابستگی‌ها را تنظیم کنید

این وابستگی‌ها را در فایل ساخت خود لحاظ کنید.

ماون

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

گرادل

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

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

هر کانکتور از یک فایل پیکربندی برای پارامترهایی مانند شناسه مخزن شما استفاده می‌کند. پارامترها را به صورت جفت‌های کلید-مقدار تعریف کنید، مانند api.sourceId= 1234567890abcdef .

کیت توسعه نرم‌افزار جستجوی ابری گوگل (Google Cloud Search SDK) شامل پارامترهای ارائه شده توسط گوگل برای همه کانکتورها است. شما باید موارد زیر را در فایل پیکربندی خود اعلام کنید:

  • رابط محتوا : api.sourceId و api.serviceAccountPrivateKeyFile را تعریف کنید. این‌ها مخزن شما و کلید خصوصی مورد نیاز برای دسترسی را مشخص می‌کنند.
  • رابط هویت : برای شناسایی منبع هویت خارجی خود، api.identitySourceId را تعریف کنید. برای همگام‌سازی کاربر، api.customerId (شناسه منحصر به فرد برای حساب Google Workspace شما) را نیز تعریف کنید.

پارامترهای ارائه شده توسط گوگل را فقط طوری تعریف کنید که مقادیر پیش‌فرض آنها لغو شود. برای جزئیات بیشتر در مورد تولید شناسه‌ها و کلیدها، به پارامترهای ارائه شده توسط گوگل مراجعه کنید.

همچنین می‌توانید پارامترهای مختص مخزن را در فایل پیکربندی خود تعریف کنید.

فایل پیکربندی را به کانکتور ارسال کنید

ویژگی سیستم config را برای ارسال فایل پیکربندی تنظیم کنید. هنگام شروع اتصال از آرگومان -D استفاده کنید. به عنوان مثال:

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

اگر این آرگومان را حذف کنید، SDK تلاش می‌کند از فایلی با نام connector-config.properties در دایرکتوری محلی استفاده کند.

استراتژی پیمایش خود را تعیین کنید

وظیفه اصلی یک رابط محتوا، پیمایش یک مخزن و فهرست‌بندی داده‌های آن است. شما باید بر اساس اندازه و طرح مخزن خود، یک استراتژی پیاده‌سازی کنید. می‌توانید استراتژی خودتان را طراحی کنید یا یک استراتژی از SDK انتخاب کنید:

استراتژی پیمایش کامل
کل مخزن را اسکن کرده و هر مورد را فهرست‌بندی می‌کند. این استراتژی برای مخازن کوچکی که می‌توانید سربار یک پیمایش کامل را در طول هر فهرست‌بندی تحمل کنید، بهترین گزینه است. از آن برای مخازن کوچکی که عمدتاً داده‌های ایستا و غیرسلسله مراتبی دارند یا زمانی که تشخیص تغییر دشوار است، استفاده کنید.
استراتژی پیمایش لیست
کل مخزن را برای تعیین وضعیت هر مورد اسکن می‌کند، سپس فقط موارد جدید یا به‌روزرسانی‌شده را فهرست‌بندی می‌کند. از این برای به‌روزرسانی‌های افزایشی یک فهرست بزرگ و غیرسلسله مراتبی، زمانی که تشخیص تغییر پشتیبانی نمی‌شود، استفاده کنید.
پیمایش گراف
یک گره والد را برای تعیین وضعیت آیتم‌های آن اسکن می‌کند، سپس آیتم‌های جدید یا به‌روزرسانی‌شده را در آن گره فهرست‌بندی می‌کند. سپس به صورت بازگشتی گره‌های فرزند را پردازش می‌کند. از این برای مخازن سلسله مراتبی که فهرست کردن همه شناسه‌ها عملی نیست، مانند ساختارهای دایرکتوری یا وب‌سایت‌ها، استفاده کنید.

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

با استفاده از یک کلاس الگو، یک رابط پیمایش کامل ایجاد کنید

این بخش به کدی از FullTraversalSample اشاره دارد.

نقطه ورود کانکتور را پیاده‌سازی کنید

نقطه ورود، متد main() است. این متد یک نمونه Application ایجاد می‌کند و start() را برای اجرای کانکتور فراخوانی می‌کند.

قبل از فراخوانی application.start() ، از کلاس IndexingApplication.Builder برای نمونه‌سازی الگوی FullTraversalConnector استفاده کنید. این الگو یک شیء Repository می‌پذیرد.

نمونه پیمایش کامل.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * traversal connector.
 *
 * @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 SampleRepository();
  IndexingConnector connector = new FullTraversalConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

SDK پس از فراخوانی Application.build() ) توسط متد main() شما، تابع initConfig() () را فراخوانی می‌کند. متد initConfig() به صورت زیر است:

  1. اطمینان حاصل می‌کند که Configuration از قبل مقداردهی اولیه نشده است.
  2. شیء Configuration را با جفت‌های کلید-مقدار ارائه شده توسط گوگل، مقداردهی اولیه می‌کند.

پیاده‌سازی رابط مخزن (Repository)

شیء Repository آیتم‌های مخزن را پیمایش و فهرست‌بندی می‌کند. هنگام استفاده از یک الگو، فقط باید متدهای خاصی را در رابط Repository بازنویسی کنید. برای FullTraversalConnector ، بازنویسی کنید:

  • init() : برای تنظیم و مقداردهی اولیه مخزن.
  • getAllDocs() : برای پیمایش و فهرست‌بندی همه آیتم‌ها. این متد برای هر پیمایش زمان‌بندی‌شده یک بار فراخوانی می‌شود.
  • (اختیاری) getChanges() : اگر مخزن شما از تشخیص تغییر پشتیبانی می‌کند، این را برای بازیابی و فهرست‌بندی موارد تغییر یافته بازنویسی کنید.
  • (اختیاری) close() : برای پاکسازی مخزن در هنگام خاموش شدن سیستم.

هر متد یک شیء ApiOperation برمی‌گرداند که با استفاده از IndexingService.indexItem() ایندکس‌گذاری را انجام می‌دهد.

دریافت پارامترهای پیکربندی سفارشی

برای مدیریت پیکربندی کانکتور خود، باید هرگونه پارامتر سفارشی را از شیء Configuration بازیابی کنید. این کار را در متد init() کلاس Repository خود انجام دهید.

کلاس Configuration شامل متدهایی برای بازیابی انواع مختلف داده است. هر متد یک شیء ConfigValue را برمی‌گرداند. از متد get() شیء ConfigValue برای بازیابی مقدار استفاده کنید. این قطعه کد از FullTraversalSample نحوه بازیابی یک مقدار صحیح سفارشی را نشان می‌دهد:

نمونه پیمایش کامل.java
@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

برای بازیابی و تجزیه پارامترهایی با چندین مقدار، از یکی از تجزیه‌کننده‌های نوع کلاس Configuration استفاده کنید. این قطعه کد از رابط آموزشی از getMultiValue برای بازیابی لیستی از نام‌های مخزن GitHub استفاده می‌کند:

مخزن گیت‌هاب.جاوا
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

انجام پیمایش کامل

برای انجام یک پیمایش کامل، تابع getAllDocs() را نادیده می‌گیرد. این متد یک نقطه‌ی بررسی می‌پذیرد تا در صورت قطع شدن، اندیس‌گذاری را از سر بگیرد. برای هر آیتم:

  1. مجوزها را تنظیم کنید.
  2. تنظیم فراداده (metadata).
  3. آنها را در یک RepositoryDoc ترکیب کنید.
  4. هر آیتم را در تکرارکننده‌ای که توسط getAllDocs() برگردانده می‌شود، بسته‌بندی کنید.

اگر مجموعه اقلام برای یک فراخوانی خیلی بزرگ است، از یک Checkpoint استفاده کنید و تابع hasMore(true) را فراخوانی کنید.

تنظیم مجوزها برای یک مورد

مخازن از لیست‌های کنترل دسترسی (ACL) برای شناسایی کاربران یا گروه‌هایی که به یک مورد دسترسی دارند استفاده می‌کنند. یک ACL، شناسه‌های کاربران یا گروه‌های مجاز را فهرست می‌کند.

برای اطمینان از اینکه کاربران فقط نتایج جستجویی را که مجاز به دسترسی به آنها هستند، مشاهده می‌کنند، باید ACL های مخزن خود را تکثیر کنید. هنگام فهرست‌بندی یک مورد، ACL را نیز لحاظ کنید تا Google Cloud Search بتواند سطح دسترسی صحیح را ارائه دهد.

کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK) شامل کلاس‌ها و روش‌هایی برای مدل‌سازی ACLهای اکثر مخازن است. ACLهای مخزن خود را تجزیه و تحلیل کنید و ACLهای مربوطه را برای جستجوی ابری (Cloud Search) در حین فهرست‌بندی ایجاد کنید. مدل‌سازی ACLهای پیچیده، مانند آن‌هایی که از وراثت استفاده می‌کنند، نیاز به برنامه‌ریزی دقیق دارد. برای اطلاعات بیشتر، به ACLهای جستجوی ابری (Cloud Search ACLs) مراجعه کنید.

از کلاس Acl.Builder برای تنظیم دسترسی استفاده کنید. این قطعه کد از نمونه کامل پیمایش به همه کاربران دامنه ( getCustomerPrincipal() ) اجازه می‌دهد همه موارد ( setReaders() ) را بخوانند:

نمونه پیمایش کامل.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

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

تنظیم فراداده برای یک آیتم

متادیتا در یک شیء Item ذخیره می‌شود. برای ایجاد یک Item ، به یک شناسه منحصر به فرد، نوع آیتم، ACL، URL و نسخه نیاز دارید. از کلاس کمکی IndexingItemBuilder استفاده کنید.

نمونه پیمایش کامل.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with appropriate attributes
// (this can be expanded to include metadata fields etc.)
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(id))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();
ایجاد آیتم قابل فهرست‌بندی

از کلاس RepositoryDoc.Builder استفاده کنید.

نمونه پیمایش کامل.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", id);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

یک RepositoryDoc یک ApiOperation است که درخواست IndexingService.indexItem() را انجام می‌دهد.

از متد setRequestMode() از کلاس RepositoryDoc.Builder برای تنظیم درخواست ایندکس‌گذاری روی ASYNCHRONOUS یا SYNCHRONOUS استفاده کنید:

ASYNCHRONOUS
این حالت تأخیر بیشتری در اندیس‌گذاری تا ارائه سرویس دارد اما سهمیه توان عملیاتی بیشتری را در خود جای می‌دهد. از حالت ناهمزمان برای اندیس‌گذاری اولیه (backfill) کل مخزن استفاده کنید.
SYNCHRONOUS
این حالت تأخیر کمتری در اندیس‌گذاری تا ارائه سرویس دارد، اما سهمیه توان عملیاتی کمتری دارد. از حالت همگام برای اندیس‌گذاری به‌روزرسانی‌ها و تغییرات مخزن استفاده کنید. در صورت عدم تعیین، حالت درخواست به صورت پیش‌فرض روی SYNCHRONOUS تنظیم می‌شود.
هر آیتم قابل فهرست‌بندی را در یک تکرارکننده بسته‌بندی کنید

متد getAllDocs() یک CheckpointCloseableIterable از اشیاء RepositoryDoc برمی‌گرداند. از کلاس CheckpointCloseableIterableImpl.Builder استفاده کنید.

نمونه پیمایش کامل.java
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

مراحل بعدی

با استفاده از یک کلاس الگو، یک رابط پیمایش لیست ایجاد کنید

صف نمایه‌سازی جستجوی ابری، شناسه‌ها و هش‌های اختیاری را برای اقلام مخزن نگه می‌دارد. یک رابط پیمایش لیست، شناسه‌ها را به این صف ارسال کرده و آنها را برای نمایه‌سازی بازیابی می‌کند. جستجوی ابری این صف‌ها را برای تعیین وضعیت اقلام، مانند حذف‌ها، نگهداری می‌کند. به صف نمایه‌سازی جستجوی ابری مراجعه کنید.

این بخش به ListTraversalSample اشاره دارد.

نقطه ورود کانکتور را پیاده‌سازی کنید

متد main() یک نمونه Application ایجاد می‌کند و start() را فراخوانی می‌کند. IndexingApplication.Builder برای نمونه‌سازی الگوی ListingConnector استفاده کنید.

نمونه پیمایش لیست.جاوا
/**
 * This sample connector uses the Cloud Search SDK template class for a
 * list traversal connector.
 *
 * @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 SampleRepository();
  IndexingConnector connector = new ListingConnector(repository);
  IndexingApplication application = new IndexingApplication.Builder(connector, args).build();
  application.start();
}

پیاده‌سازی رابط مخزن (Repository)

متدهای زیر را برای ListingConnector بازنویسی کنید:

  • init() : برای تنظیم مخزن.
  • getIds() : برای بازیابی شناسه‌ها و هش‌ها برای همه رکوردها.
  • getDoc() : برای اضافه کردن، به‌روزرسانی یا حذف آیتم‌ها از ایندکس.
  • (اختیاری) getChanges() : برای به‌روزرسانی‌های افزایشی با استفاده از تشخیص تغییر.
  • (اختیاری) close() : برای پاکسازی مخزن.

پیمایش لیست را انجام دهید

برای بازیابی شناسه‌ها و هش‌ها، تابع getIds() را بازنویسی کنید. برای مدیریت هر آیتم در صف نمایه‌سازی جستجوی ابری، تابع getDoc() را بازنویسی کنید.

شناسه‌های آیتم و مقادیر هش را فشار دهید

برای دریافت شناسه‌ها و هش‌های محتوا، getIds() را بازنویسی کنید. آن‌ها را در یک درخواست PushItems به صف نمایه‌سازی بسته‌بندی کنید.

نمونه پیمایش لیست.جاوا
PushItems.Builder allIds = new PushItems.Builder();
for (Map.Entry<Integer, Long> entry : this.documents.entrySet()) {
  String documentId = Integer.toString(entry.getKey());
  String hash = this.calculateMetadataHash(entry.getKey());
  PushItem item = new PushItem().setMetadataHash(hash);
  log.info("Pushing " + documentId);
  allIds.addPushItem(documentId, item);
}

از PushItems.Builder برای بسته‌بندی شناسه‌ها و هش‌ها استفاده کنید.

نمونه پیمایش لیست.جاوا
ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;
بازیابی و مدیریت هر مورد

برای مدیریت آیتم‌های موجود در صف فهرست‌بندی، getDoc() را بازنویسی کنید. آیتم‌ها می‌توانند جدید، اصلاح‌شده، بدون تغییر یا حذف‌شده باشند.

  1. بررسی کنید که آیا شناسه‌ی آیتم در مخزن وجود دارد یا خیر. اگر نه، آن را حذف کنید.
  2. وضعیت را از شاخص نظرسنجی کنید. اگر تغییر نکرده ( ACCEPTED )، هیچ کاری انجام ندهید.
  3. فهرست کردن موارد تغییر یافته یا جدید: تنظیم مجوزها، تنظیم فراداده، ترکیب در یک RepositoryDoc و بازگرداندن آن.
رسیدگی به موارد حذف شده

این قطعه کد نشان می‌دهد که چگونه می‌توان وجود یک آیتم را تشخیص داد و در صورت عدم وجود، آن را حذف کرد.

نمونه پیمایش لیست.جاوا
String resourceName = item.getName();
int documentId = Integer.parseInt(resourceName);

if (!documents.containsKey(documentId)) {
  // Document no longer exists -- delete it
  log.info(() -> String.format("Deleting document %s", item.getName()));
  return ApiOperations.deleteItem(resourceName);
}
رسیدگی به موارد بدون تغییر

برای مدیریت موارد بدون تغییر، صف فهرست‌بندی را بررسی کنید.

نمونه پیمایش لیست.جاوا
String currentHash = this.calculateMetadataHash(documentId);
if (this.canSkipIndexing(item, currentHash)) {
  // Document neither modified nor deleted, ack the push
  log.info(() -> String.format("Document %s not modified", item.getName()));
  PushItem pushItem = new PushItem().setType("NOT_MODIFIED");
  return new PushItems.Builder().addPushItem(resourceName, pushItem).build();
}

این مثال از یک هش برای تشخیص تغییرات استفاده می‌کند.

نمونه پیمایش لیست.جاوا
/**
 * Checks to see if an item is already up to date
 *
 * @param previousItem Polled item
 * @param currentHash  Metadata hash of the current github object
 * @return PushItem operation
 */
private boolean canSkipIndexing(Item previousItem, String currentHash) {
  if (previousItem.getStatus() == null || previousItem.getMetadata() == null) {
    return false;
  }
  String status = previousItem.getStatus().getCode();
  String previousHash = previousItem.getMetadata().getHash();
  return "ACCEPTED".equals(status)
      && previousHash != null
      && previousHash.equals(currentHash);
}
تنظیم مجوزها برای یک مورد

مخازن از لیست‌های کنترل دسترسی (ACL) برای شناسایی کاربران یا گروه‌هایی که به یک مورد دسترسی دارند استفاده می‌کنند. یک ACL، شناسه‌های کاربران یا گروه‌های مجاز را فهرست می‌کند.

برای اطمینان از اینکه کاربران فقط نتایج جستجویی را که مجاز به دسترسی به آنها هستند، مشاهده می‌کنند، باید ACL های مخزن خود را تکثیر کنید. هنگام فهرست‌بندی یک مورد، ACL را نیز لحاظ کنید تا Google Cloud Search بتواند سطح دسترسی صحیح را ارائه دهد.

کیت توسعه نرم‌افزار رابط محتوا (Content Connector SDK) شامل کلاس‌ها و روش‌هایی برای مدل‌سازی ACLهای اکثر مخازن است. ACLهای مخزن خود را تجزیه و تحلیل کنید و ACLهای مربوطه را برای جستجوی ابری (Cloud Search) در حین فهرست‌بندی ایجاد کنید. مدل‌سازی ACLهای پیچیده، مانند آن‌هایی که از وراثت استفاده می‌کنند، نیاز به برنامه‌ریزی دقیق دارد. برای اطلاعات بیشتر، به ACLهای جستجوی ابری (Cloud Search ACLs) مراجعه کنید.

از کلاس Acl.Builder برای تنظیم دسترسی استفاده کنید. این قطعه کد از نمونه کامل پیمایش به همه کاربران دامنه ( getCustomerPrincipal() ) اجازه می‌دهد همه موارد ( setReaders() ) را بخوانند:

نمونه پیمایش کامل.java
// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

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

تنظیم فراداده برای یک آیتم
نمونه پیمایش لیست.جاوا
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Set metadata hash so queue can detect changes
String metadataHash = this.calculateMetadataHash(documentId);

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(Integer.toString(documentId))
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .setHash(metadataHash)
    .build();
ایجاد یک آیتم قابل فهرست‌بندی
نمونه پیمایش لیست.جاوا
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %d", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

// Create the fully formed document
RepositoryDoc doc = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT)
    .build();

از متد setRequestMode() از کلاس RepositoryDoc.Builder برای تنظیم درخواست ایندکس‌گذاری روی ASYNCHRONOUS یا SYNCHRONOUS استفاده کنید:

ASYNCHRONOUS
این حالت تأخیر بیشتری در اندیس‌گذاری تا ارائه سرویس دارد اما سهمیه توان عملیاتی بیشتری را در خود جای می‌دهد. از حالت ناهمزمان برای اندیس‌گذاری اولیه (backfill) کل مخزن استفاده کنید.
SYNCHRONOUS
این حالت تأخیر کمتری در اندیس‌گذاری تا ارائه سرویس دارد، اما سهمیه توان عملیاتی کمتری دارد. از حالت همگام برای اندیس‌گذاری به‌روزرسانی‌ها و تغییرات مخزن استفاده کنید. در صورت عدم تعیین، حالت درخواست به صورت پیش‌فرض روی SYNCHRONOUS تنظیم می‌شود.

مراحل بعدی

در اینجا چند گام بعدی که می‌توانید بردارید، آورده شده است:

ایجاد یک رابط پیمایش گراف با استفاده از یک کلاس الگو

صف نمایه‌سازی جستجوی ابری، شناسه‌ها و مقادیر هش اختیاری را برای هر مورد در مخزن نگه می‌دارد. یک رابط پیمایش گراف، شناسه‌های مورد را به صف نمایه‌سازی جستجوی ابری گوگل ارسال می‌کند و آنها را یکی یکی برای نمایه‌سازی بازیابی می‌کند. جستجوی ابری گوگل، صف‌ها را نگهداری می‌کند و محتوای صف را برای تعیین وضعیت مورد، مانند اینکه آیا یک مورد از مخزن حذف شده است یا خیر، مقایسه می‌کند. برای اطلاعات بیشتر در مورد صف نمایه‌سازی جستجوی ابری، به صف نمایه‌سازی جستجوی ابری گوگل مراجعه کنید.

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

نقطه ورود کانکتور را پیاده‌سازی کنید

نقطه ورود به یک کانکتور، متد main() است. این متد یک نمونه از کلاس Application ایجاد می‌کند و متد start() آن را برای اجرای کانکتور فراخوانی می‌کند.

Before calling application.start() , use the IndexingApplication.Builder class to instantiate the ListingConnector template. The ListingConnector accepts a Repository object whose methods you implement.

Implement the Repository interface

Override init() , getIds() , getDoc() , and optionally getChanges() or close() .

Perform the graph traversal

Override getIds() to retrieve initial IDs and getDoc() to handle items and push child IDs to the queue.

Push item IDs and hash values
GraphTraversalSample.java
PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);
Retrieve and handle each item
  1. Check if the ID exists in the repository. If not, delete the item.
  2. For existing items, set permissions and metadata, and combine them into a RepositoryDoc .
  3. Push child IDs to the Indexing Queue.
  4. Return the RepositoryDoc .
Handle deleted items
GraphTraversalSample.java
String resourceName = item.getName();
if (documentExists(resourceName)) {
  return buildDocumentAndChildren(resourceName);
}
// Document doesn't exist, delete it
log.info(() -> String.format("Deleting document %s", resourceName));
return ApiOperations.deleteItem(resourceName);
Set metadata and create the item
GraphTraversalSample.java
// Url is required. Use google.com as a placeholder for this sample.
String viewUrl = "https://www.google.com";

// Version is required, set to current timestamp.
byte[] version = Longs.toByteArray(System.currentTimeMillis());

// Using the SDK item builder class to create the document with
// appropriate attributes. This can be expanded to include metadata
// fields etc.
Item item = IndexingItemBuilder.fromConfiguration(documentId)
    .setItemType(IndexingItemBuilder.ItemType.CONTENT_ITEM)
    .setAcl(acl)
    .setSourceRepositoryUrl(IndexingItemBuilder.FieldOrValue.withValue(viewUrl))
    .setVersion(version)
    .build();
GraphTraversalSample.java
// For this sample, content is just plain text
String content = String.format("Hello world from sample doc %s", documentId);
ByteArrayContent byteContent = ByteArrayContent.fromString("text/plain", content);

RepositoryDoc.Builder docBuilder = new RepositoryDoc.Builder()
    .setItem(item)
    .setContent(byteContent, IndexingService.ContentFormat.TEXT);
Place child IDs in the Indexing Queue
GraphTraversalSample.java
// Queue the child nodes to visit after indexing this document
Set<String> childIds = getChildItemNames(documentId);
for (String id : childIds) {
  log.info(() -> String.format("Pushing child node %s", id));
  PushItem pushItem = new PushItem();
  docBuilder.addChildId(id, pushItem);
}

RepositoryDoc doc = docBuilder.build();

Create a content connector using the REST API

The following sections explain how to create a content connector using the REST API.

Determine your traversal strategy

The strategies (Full, List, and Graph) are conceptually the same as for the SDK. Implement your chosen strategy using the REST API.

Implement your traversal strategy and index items

Register your schema, then populate the index using:

  1. (Optional) items.upload for files larger than 100 KiB.
  2. (Optional) media.upload for media files.

  3. items.index to index the item.

    Example indexing request: 

    {
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "viewUrl": "http://www.imdb.com/title/tt2234155/",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [
        {
          "name": "movieTitle",
          "textValues": { "values": ["Titanic"] }
        }
      ]
    }
  },
  "content": {
    "inlineContent": "A seventeen-year-old aristocrat falls in love...",
    "contentFormat": "TEXT"
  },
  "version": "01",
  "itemType": "CONTENT_ITEM"
}

  4. (Optional) Use items.get to verify indexing.

Handle repository changes

Periodically reindex the entire repository for full indexing. For list or graph traversal, use the Google Cloud Indexing Queue to track changes and only index what has changed. Use items.push to add items to the queue.