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

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

• Content Connector SDK. اگر به زبان جاوا برنامه نویسی می کنید این گزینه خوبی است. Content Connector SDK یک بسته بندی در اطراف REST API است که به شما امکان می دهد به سرعت اتصالات ایجاد کنید. برای ایجاد یک رابط محتوا با استفاده از SDK، به ایجاد رابط محتوا با استفاده از Content Connector SDK مراجعه کنید.

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

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

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

با استفاده از Content Connector SDK یک رابط محتوا ایجاد کنید

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

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

برای استفاده از SDK باید وابستگی های خاصی را در فایل ساخت خود قرار دهید. برای مشاهده وابستگی های محیط ساخت خود، روی یک تب زیر کلیک کنید:

ماون

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

گریدل

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

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

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

Google Cloud Search SDK حاوی چندین پارامتر پیکربندی ارائه شده توسط Google است که توسط همه رابط‌ها استفاده می‌شود. شما باید پارامترهای ارائه شده توسط Google را در فایل پیکربندی خود اعلام کنید:

• برای اتصال محتوا، باید api.sourceId و api.serviceAccountPrivateKeyFile را اعلام کنید زیرا این پارامترها مکان مخزن شما و کلید خصوصی مورد نیاز برای دسترسی به مخزن را مشخص می کنند.

توجه: اگر فایل کلید خصوصی شما یک کلید JSON نیست، باید api.serviceAccountId نیز لغو کنید.

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

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

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

توجه: هیچ الزام نامگذاری دقیقی برای فایل ویژگی های رابط وجود ندارد، اما توصیه می کنیم فایل را با استفاده از یک .properties یا پسوند .config ذخیره کنید.

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

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

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

اگر این آرگومان وجود نداشته باشد، SDK سعی می کند به یک فایل پیکربندی پیش فرض به نام connector-config.properties دسترسی پیدا کند.

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

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

استراتژی پیمایش کامل

یک استراتژی کامل پیمایش کل مخزن را اسکن می کند و کورکورانه هر آیتم را فهرست می کند. این استراتژی معمولاً زمانی استفاده می‌شود که شما یک مخزن کوچک دارید و می‌توانید هر بار که ایندکس می‌کنید، هزینه سربار انجام یک پیمایش کامل را بپردازید.

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

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

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

این استراتژی پیمایش زمانی مناسب است که تشخیص تغییر مشکل است یا توسط مخزن پشتیبانی نمی شود، داده های غیر سلسله مراتبی دارید و با مجموعه داده های بسیار بزرگی کار می کنید.

پیمایش نمودار

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

اگر داده های سلسله مراتبی دارید که باید خزیده شوند، مانند یک سری دایرکتوری یا صفحات وب، این استراتژی مناسب است.

توجه: اصطلاحات "اقلام" و "سند" در این سند و کد نمونه مترادف هستند.

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

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

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

این بخش از اسناد به قطعات کد از مثال FullTraversalSample اشاره دارد.

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

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

قبل از فراخوانی application.start() از کلاس IndexingApplication.Builder برای نمونه سازی قالب FullTraversalConnector استفاده کنید. FullTraversalConnector یک شی Repository را می پذیرد که روش های آن را پیاده سازی می کنید. قطعه کد زیر نحوه پیاده سازی متد main() نشان می دهد:

FullTraversalSample.java

در GitHub مشاهده کنید

/**
 * 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 متد initConfig() را پس از فراخوانی متد main() کانکتور شما Application.build فراخوانی می کند. متد initConfig() وظایف زیر را انجام می دهد:

1. متد Configuation.isInitialized() را فراخوانی می کند تا مطمئن شود که Configuration اولیه نشده است.
2. یک شی Configuration با جفت های کلید-مقدار ارائه شده توسط Google راه اندازی می کند. هر جفت کلید-مقدار در یک شی ConfigValue در شی Configuration ذخیره می شود.

رابط Repository را پیاده سازی کنید

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

• متد init() . برای انجام هرگونه راه اندازی و مقداردهی اولیه مخزن داده، روش init() را نادیده بگیرید.

• متد getAllDocs() . برای پیمایش و فهرست کردن همه موارد موجود در مخزن داده، روش getAllDocs() را لغو کنید. این روش یک بار برای هر پیمایش زمانبندی شده (همانطور که توسط پیکربندی شما تعریف شده است) فراخوانی می شود.

• (اختیاری) متد getChanges() . اگر مخزن شما از تشخیص تغییر پشتیبانی می کند، متد getChanges() را لغو کنید. این روش یک بار برای هر پیمایش افزایشی برنامه ریزی شده (همانطور که توسط پیکربندی شما تعریف شده است) فراخوانی می شود تا موارد اصلاح شده را بازیابی کرده و آنها را فهرست بندی کند.

• (اختیاری) متد close() . اگر نیاز به پاکسازی مخزن دارید، متد close() را لغو کنید. این روش یک بار در هنگام خاموش شدن کانکتور فراخوانی می شود.

هر یک از متدهای شی Repository نوعی از شیء ApiOperation را برمی گرداند. یک شیء ApiOperation عملی را به شکل یک یا شاید چند فراخوانی IndexingService.indexItem() انجام می دهد تا نمایه سازی واقعی مخزن شما را انجام دهد.

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

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

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

FullTraversalSample.java

در GitHub مشاهده کنید

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

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

GithubRepository.java

در GitHub مشاهده کنید

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

پیمایش کامل را انجام دهید

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

1. مجوزها را تنظیم کنید.
2. متادیتا را برای موردی که در حال نمایه سازی هستید تنظیم کنید.
3. ابرداده و مورد را در یک RepositoryDoc قابل نمایه سازی ترکیب کنید.
4. هر آیتم قابل نمایه سازی را در یک تکرارکننده که توسط متد getAllDocs() برگردانده شده است، بسته بندی کنید. توجه داشته باشید که getAllDocs() در واقع یک CheckpointCloseableIterable را برمی گرداند که تکراری از اشیاء ApiOperation است، که هر شی نشان دهنده یک درخواست API است که روی یک RepositoryDoc انجام می شود، مانند نمایه سازی آن.

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

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

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

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

Content Connector SDK مجموعه ای غنی از کلاس ها و روش های ACL را برای مدل سازی ACL های اکثر مخازن ارائه می دهد. شما باید ACL را برای هر مورد در مخزن خود تجزیه و تحلیل کنید و هنگامی که یک مورد را فهرست می کنید، ACL مربوطه را برای جستجوی ابری Google ایجاد کنید. اگر ACL مخزن شما از مفاهیمی مانند وراثت ACL استفاده می کند، مدل سازی آن ACL می تواند مشکل باشد. برای اطلاعات بیشتر در مورد Google Cloud Search ACL، به Google Cloud Search ACL مراجعه کنید.

توجه: Cloud Search Indexing API از ACL های تک دامنه پشتیبانی می کند. از ACL های متقابل دامنه پشتیبانی نمی کند. از کلاس Acl.Builder برای تنظیم دسترسی به هر آیتم با استفاده از یک ACL استفاده کنید. قطعه کد زیر، که از نمونه پیمایش کامل گرفته شده است، به همه کاربران یا "اصول" ( getCustomerPrincipal() ) اجازه می دهد تا "خوانندگان" همه موارد ( .setReaders() ) در هنگام انجام جستجو باشند.

FullTraversalSample.java

در GitHub مشاهده کنید

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

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

متادیتا را برای یک مورد تنظیم کنید

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

FullTraversalSample.java

در GitHub مشاهده کنید

// 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 ایجاد کنید. مثال زیر نحوه ایجاد یک آیتم قابل نمایه سازی را نشان می دهد.

FullTraversalSample.java

در GitHub مشاهده کنید

// 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() یک Iterator ، به ویژه یک CheckpointCloseableIterable ، از اشیاء RepositoryDoc را برمی گرداند. می توانید از کلاس CheckpointClosableIterableImpl.Builder برای ساختن و برگرداندن یک تکرار کننده استفاده کنید. قطعه کد زیر نحوه ساخت و برگرداندن یک تکرار کننده را نشان می دهد.

FullTraversalSample.java

در GitHub مشاهده کنید

CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(allDocs).build();

SDK هر فراخوان نمایه سازی محصور شده در تکرار کننده را اجرا می کند.

توجه: Cloud Search داده های متا را برای همه فایل ها نمایه می کند. بسته به نوع فایل یک مورد، جستجوی ابری محتوای متن را نیز نمایه می‌کند، از جمله استفاده از تشخیص کاراکتر نوری (OCR) روی تصویر و سایر فایل‌ها. برای فهرست انواع فایل‌هایی که از استخراج متن پشتیبانی می‌کنند، به انواع فایل‌های پشتیبانی شده برای استخراج متن مراجعه کنید.

مراحل بعدی

در اینجا چند مرحله بعدی وجود دارد که ممکن است بردارید:

• (اختیاری) اگر توان نمایه سازی شما کند به نظر می رسد، به افزایش نرخ نمایه سازی برای FullTraversalConnector مراجعه کنید.
• (اختیاری) روش close() را برای آزاد کردن هر منبعی قبل از خاموش شدن اجرا کنید.
• (اختیاری) با استفاده از Content Connector SDK یک رابط هویت ایجاد کنید .

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

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

این بخش از اسناد به قطعات کد از مثال ListTraversalSample اشاره دارد.

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

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

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

ListTraversalSample.java

در GitHub مشاهده کنید

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

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

1. متد Configuation.isInitialized() را فراخوانی می کند تا مطمئن شود که Configuration اولیه نشده است.
2. یک شی Configuration با جفت های کلید-مقدار ارائه شده توسط Google راه اندازی می کند. هر جفت کلید-مقدار در یک شی ConfigValue در شی Configuration ذخیره می شود.

رابط Repository را پیاده سازی کنید

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

• متد init() . برای انجام هرگونه راه اندازی و مقداردهی اولیه مخزن داده، روش init() را نادیده بگیرید.

• متد getIds() . برای بازیابی شناسه ها و مقادیر هش برای همه رکوردهای موجود در مخزن، متد getIds() را لغو کنید.

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

• (اختیاری) متد getChanges() . اگر مخزن شما از تشخیص تغییر پشتیبانی می کند، متد getChanges() را لغو کنید. این روش یک بار برای هر پیمایش افزایشی برنامه ریزی شده (همانطور که توسط پیکربندی شما تعریف شده است) فراخوانی می شود تا موارد اصلاح شده را بازیابی کرده و آنها را فهرست بندی کند.

• (اختیاری) متد close() . اگر نیاز به پاکسازی مخزن دارید، متد close() را لغو کنید. این روش یک بار در هنگام خاموش شدن کانکتور فراخوانی می شود.

هر یک از متدهای شی Repository نوعی از شیء ApiOperation را برمی گرداند. یک شیء ApiOperation عملی را به شکل یک یا شاید چند فراخوانی IndexingService.indexItem() انجام می دهد تا نمایه سازی واقعی مخزن شما را انجام دهد.

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

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

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

FullTraversalSample.java

در GitHub مشاهده کنید

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

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

GithubRepository.java

در GitHub مشاهده کنید

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

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

برای بازیابی شناسه ها و مقادیر هش برای همه رکوردهای موجود در مخزن، روش getIds() را لغو کنید. متد getIds() یک چک پوینت را می پذیرد. در صورت قطع شدن فرآیند، از نقطه بازرسی برای از سرگیری نمایه سازی در یک مورد خاص استفاده می شود.

در مرحله بعد، متد getDoc() را برای مدیریت هر آیتم در صف فهرست بندی جستجوی ابری نادیده بگیرید.

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

برای واکشی شناسه‌های آیتم و مقادیر هش محتوای مرتبط با آنها از مخزن، getIds() لغو کنید. سپس جفت‌های ID و مقدار هش در درخواست عملیات فشار به صف فهرست‌سازی جستجوی ابری بسته‌بندی می‌شوند. شناسه های ریشه یا والد معمولاً ابتدا و سپس شناسه های فرزند تا زمانی که کل سلسله مراتب موارد پردازش شود، فشار داده می شود.

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

• شناسه هر مورد و مقدار هش مربوطه را از مخزن دریافت کنید.
• هر جفت شناسه و مقدار هش را در یک PushItems بسته بندی کنید.
• هر PushItems در یک تکرار کننده که توسط متد getIds() برگردانده شده است ترکیب کنید. توجه داشته باشید که getIds() در واقع یک CheckpointCloseableIterable را برمی گرداند که تکراری از اشیاء ApiOperation است، هر شی نشان دهنده یک درخواست API انجام شده در RepositoryDoc است، مانند فشار دادن آیتم ها به صف.

قطعه کد زیر نحوه دریافت شناسه و مقدار هش هر مورد و درج آنها را در PushItems نشان می دهد. PushItems یک درخواست ApiOperation برای فشار دادن یک آیتم به صف فهرست بندی جستجوی ابری است.

ListTraversalSample.java

در GitHub مشاهده کنید

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 نشان می دهد.

ListTraversalSample.java

در GitHub مشاهده کنید

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();
return iterator;

موارد برای پردازش بیشتر به صف فهرست بندی جستجوی ابری منتقل می شوند.

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

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

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

1. بررسی کنید که آیا شناسه مورد، در صف فهرست بندی جستجوی ابری، در مخزن وجود دارد یا خیر. اگر نه، مورد را از فهرست حذف کنید.

2. فهرست را برای وضعیت مورد نظرسنجی کنید و اگر موردی تغییر نکرد ( ACCEPTED )، کاری انجام ندهید.

3. فهرست تغییرات یا موارد جدید:

   1. مجوزها را تنظیم کنید.
   2. متادیتا را برای موردی که در حال نمایه سازی هستید تنظیم کنید.
   3. ابرداده و مورد را در یک RepositoryDoc قابل نمایه سازی ترکیب کنید.
   4. RepositoryDoc را برگردانید.

توجه: الگوی ListingConnector از برگرداندن null در متد getDoc() پشتیبانی نمی کند. برگرداندن null منجر به NullPointerException.

موارد حذف شده را مدیریت کنید

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

ListTraversalSample.java

در GitHub مشاهده کنید

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);
}

توجه داشته باشید که documents یک ساختار داده ای است که مخزن را نشان می دهد. اگر documentID در documents یافت نشد، APIOperations.deleteItem(resourceName) را برگردانید تا مورد را از فهرست حذف کنید.

موارد بدون تغییر را مدیریت کنید

قطعه کد زیر نحوه نظرسنجی وضعیت مورد در صف فهرست بندی جستجوی ابری و مدیریت یک مورد بدون تغییر را نشان می دهد.

ListTraversalSample.java

در GitHub مشاهده کنید

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();
}

برای تعیین اینکه آیا مورد اصلاح نشده است یا خیر، وضعیت مورد و همچنین سایر ابرداده هایی را که ممکن است نشان دهنده تغییر باشد بررسی کنید. در مثال، هش ابرداده برای تعیین اینکه آیا مورد تغییر کرده است یا خیر استفاده می شود.

ListTraversalSample.java

در GitHub مشاهده کنید

/**
 * 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 را برای هر مورد در مخزن خود تجزیه و تحلیل کنید و هنگامی که یک مورد را فهرست می کنید، ACL مربوطه را برای جستجوی ابری Google ایجاد کنید. اگر ACL مخزن شما از مفاهیمی مانند وراثت ACL استفاده می کند، مدل سازی آن ACL می تواند مشکل باشد. برای اطلاعات بیشتر در مورد Google Cloud Search ACL، به Google Cloud Search ACL مراجعه کنید.

توجه: Cloud Search Indexing API از ACL های تک دامنه پشتیبانی می کند. از ACL های متقابل دامنه پشتیبانی نمی کند. از کلاس Acl.Builder برای تنظیم دسترسی به هر آیتم با استفاده از یک ACL استفاده کنید. قطعه کد زیر، که از نمونه پیمایش کامل گرفته شده است، به همه کاربران یا "اصول" ( getCustomerPrincipal() ) اجازه می دهد تا "خوانندگان" همه موارد ( .setReaders() ) در هنگام انجام جستجو باشند.

FullTraversalSample.java

در GitHub مشاهده کنید

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

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

متادیتا را برای یک مورد تنظیم کنید

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

ListTraversalSample.java

در GitHub مشاهده کنید

// 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();

یک مورد قابل نمایه سازی ایجاد کنید

هنگامی که متادیتا را برای آیتم تنظیم کردید، می توانید با استفاده از RepositoryDoc.Builder آیتم قابل نمایه سازی واقعی را ایجاد کنید. مثال زیر نحوه ایجاد یک آیتم قابل نمایه سازی را نشان می دهد.

ListTraversalSample.java

در GitHub مشاهده کنید

// 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();

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

همچنین می توانید از متد setRequestMode() کلاس RepositoryDoc.Builder برای شناسایی درخواست نمایه سازی به عنوان ASYNCHRONOUS یا SYNCHRONOUS استفاده کنید:

ASYNCHRONOUS

حالت ناهمزمان منجر به تأخیر طولانی‌تر نمایه‌سازی به سرویس می‌شود و سهمیه توان عملیاتی زیادی را برای درخواست‌های نمایه‌سازی در نظر می‌گیرد. حالت ناهمزمان برای نمایه سازی اولیه (backfill) کل مخزن توصیه می شود.

SYNCHRONOUS

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

توجه: Cloud Search داده های متا را برای همه فایل ها نمایه می کند. بسته به نوع فایل یک مورد، جستجوی ابری محتوای متن را نیز نمایه می‌کند، از جمله استفاده از تشخیص کاراکتر نوری (OCR) در محتوای دست‌نویس. برای فهرست انواع فایل‌هایی که از استخراج متن پشتیبانی می‌کنند، به انواع فایل‌های پشتیبانی شده برای استخراج متن مراجعه کنید.

مراحل بعدی

در اینجا چند مرحله بعدی وجود دارد که ممکن است بردارید:

• (اختیاری) روش close() را برای آزاد کردن هر منبعی قبل از خاموش شدن اجرا کنید.
• (اختیاری) با استفاده از Content Connector SDK یک رابط هویت ایجاد کنید .

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

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

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

این بخش از اسناد به قطعات کد از مثال GraphTraversalSample اشاره دارد.

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

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

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

توجه: استراتژی پیمایش نمودار از همان کلاس الگو، ListingConnector ، به عنوان استراتژی پیمایش لیست استفاده می کند.

قطعه زیر نحوه نمونه سازی ListingConnector و Repository مرتبط با آن را نشان می دهد:

GraphTraversalSample.java

در GitHub مشاهده کنید

/**
 * This sample connector uses the Cloud Search SDK template class for a graph
 * 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();
}

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

1. متد Configuation.isInitialized() را فراخوانی می کند تا مطمئن شود که Configuration اولیه نشده است.
2. یک شی Configuration با جفت های کلید-مقدار ارائه شده توسط Google راه اندازی می کند. هر جفت کلید-مقدار در یک شی ConfigValue در شی Configuration ذخیره می شود.

رابط Repository را پیاده سازی کنید

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

• متد init() . برای انجام هرگونه راه اندازی و مقداردهی اولیه مخزن داده، روش init() را نادیده بگیرید.

• متد getIds() . برای بازیابی شناسه ها و مقادیر هش برای همه رکوردهای موجود در مخزن، متد getIds() را لغو کنید.

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

• (اختیاری) متد getChanges() . اگر مخزن شما از تشخیص تغییر پشتیبانی می کند، متد getChanges() را لغو کنید. این روش یک بار برای هر پیمایش افزایشی برنامه ریزی شده (همانطور که توسط پیکربندی شما تعریف شده است) فراخوانی می شود تا موارد اصلاح شده را بازیابی کرده و آنها را فهرست بندی کند.

• (اختیاری) متد close() . اگر نیاز به پاکسازی مخزن دارید، متد close() را لغو کنید. این روش یک بار در هنگام خاموش شدن کانکتور فراخوانی می شود.

هر یک از متدهای شی Repository نوعی از شیء ApiOperation را برمی گرداند. یک شیء ApiOperation عملی را به شکل یک یا شاید چند فراخوانی IndexingService.indexItem() انجام می دهد تا نمایه سازی واقعی مخزن شما را انجام دهد.

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

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

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

FullTraversalSample.java

در GitHub مشاهده کنید

@Override
public void init(RepositoryContext context) {
  log.info("Initializing repository");
  numberOfDocuments = Configuration.getInteger("sample.documentCount", 10).get();
}

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

GithubRepository.java

در GitHub مشاهده کنید

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

پیمایش نمودار را انجام دهید

برای بازیابی شناسه ها و مقادیر هش برای همه رکوردهای موجود در مخزن، روش getIds() را لغو کنید. متد getIds() یک چک پوینت را می پذیرد. در صورت قطع شدن فرآیند، از نقطه بازرسی برای از سرگیری نمایه سازی در یک مورد خاص استفاده می شود.

در مرحله بعد، متد getDoc() را برای مدیریت هر آیتم در صف فهرست بندی جستجوی ابری نادیده بگیرید.

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

برای واکشی شناسه‌های آیتم و مقادیر هش محتوای مرتبط با آنها از مخزن، getIds() لغو کنید. سپس جفت‌های ID و مقدار هش در درخواست عملیات فشار به صف فهرست‌سازی جستجوی ابری بسته‌بندی می‌شوند. شناسه های ریشه یا والد معمولاً ابتدا و سپس شناسه های فرزند تا زمانی که کل سلسله مراتب موارد پردازش شود، فشار داده می شود.

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

• شناسه هر مورد و مقدار هش مربوطه را از مخزن دریافت کنید.
• هر جفت شناسه و مقدار هش را در یک PushItems بسته بندی کنید.
• هر PushItems در یک تکرار برگشتی با روش getIds() ترکیب کنید. توجه داشته باشید که getIds() در واقع یک CheckpointCloseableIterable که تکرار اشیاء ApiOperation است ، هر شیء نمایانگر یک درخواست API است که بر روی یک RepositoryDoc انجام می شود ، مانند فشار دادن موارد به صف.

قطعه کد زیر نشان می دهد که چگونه می توان شناسه و ارزش هش را به دست آورد و آنها را در یک PushItems قرار داد. PushItems یک درخواست ApiOperation برای فشار دادن یک مورد به صف فهرست بندی جستجوی ابر است.

graphtraversalsample.java

در GitHub مشاهده کنید

PushItems.Builder allIds = new PushItems.Builder();
PushItem item = new PushItem();
allIds.addPushItem("root", item);

قطعه کد زیر نحوه استفاده از کلاس PushItems.Builder را برای بسته بندی شناسه ها و مقادیر هش در یک ApiOperation فشار نشان می دهد.

graphtraversalsample.java

در GitHub مشاهده کنید

ApiOperation pushOperation = allIds.build();
CheckpointCloseableIterable<ApiOperation> iterator =
  new CheckpointCloseableIterableImpl.Builder<>(
      Collections.singletonList(pushOperation))
  .build();

موارد برای پردازش بیشتر به صف فهرست بندی جستجوی ابر منتقل می شوند.

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

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

روش getDoc() موردی را از صف فهرست بندی جستجوی Cloud می پذیرد. برای هر مورد در صف ، این مراحل را در روش getDoc() انجام دهید:

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

2. فهرست تغییر یافته یا موارد جدید:

   1. مجوزها را تنظیم کنید.
   2. ابرداده را برای کالایی که در آن فهرست بندی می کنید تنظیم کنید.
   3. ابرداده و مورد را در یک RepositoryDoc شاخص قابل استفاده ترکیب کنید.
   4. برای پردازش بیشتر شناسه های کودک را در صف فهرست بندی جستجوی ابر قرار دهید.
   5. RepositoryDoc را برگردانید.

موارد حذف شده را کنترل کنید

قطعه کد زیر نشان می دهد که چگونه یک مورد در فهرست وجود داشته باشد و ، آن را حذف نمی کند.

graphtraversalsample.java

در GitHub مشاهده کنید

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);

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

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

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

اتصال دهنده محتوا SDK مجموعه ای غنی از کلاس ها و روش های ACL را برای مدل سازی ACL های اکثر مخازن فراهم می کند. شما باید ACL را برای هر مورد در مخزن خود تجزیه و تحلیل کنید و هنگام فهرست کردن یک مورد ، ACL مربوطه را برای جستجوی Google Cloud ایجاد کنید. اگر ACL مخزن شما از مفاهیمی مانند وراثت ACL استفاده می کند ، مدل سازی می کند که ACL می تواند مشکل باشد. برای کسب اطلاعات بیشتر در مورد ACL های جستجوی Google Cloud ، به Google Cloud Search ACLS مراجعه کنید.

توجه: API نمایه سازی جستجوی ابر از ACL های تک دامنه پشتیبانی می کند. از ACL های متقابل دامنه پشتیبانی نمی کند. برای تنظیم دسترسی به هر مورد با استفاده از ACL از کلاس Acl.Builder استفاده کنید. قطعه کد زیر ، که از نمونه کامل Traversal گرفته شده است ، به کلیه کاربران یا "اصولگرایان" ( getCustomerPrincipal() ) اجازه می دهد تا هنگام انجام جستجو ، "خواننده" همه موارد ( .setReaders() ) باشند.

fulltraversalsample.java

در GitHub مشاهده کنید

// Make the document publicly readable within the domain
Acl acl = new Acl.Builder()
    .setReaders(Collections.singletonList(Acl.getCustomerPrincipal()))
    .build();

برای مدل سازی صحیح ACL برای مخزن ، باید ACL ها را درک کنید. به عنوان مثال ، شما ممکن است در یک سیستم فایل که از نوعی مدل وراثت استفاده می کند ، در حال فهرست بندی پرونده ها باشید که به موجب آن پوشه های کودک مجوزها را از پوشه های والدین به ارث می برند. مدل سازی وراثت ACL نیاز به اطلاعات اضافی در Google Cloud ACL دارد

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

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

graphtraversalsample.java

در GitHub مشاهده کنید

// 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();

مورد قابل فهرست را ایجاد کنید

پس از تنظیم ابرداده برای مورد ، می توانید با استفاده از RepositoryDoc.Builder مورد قابل فهرست بندی واقعی را ایجاد کنید. مثال زیر نحوه ایجاد یک مورد قابل فهرست را نشان می دهد.

graphtraversalsample.java

در GitHub مشاهده کنید

// 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);

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

همچنین می توانید از روش setRequestMode() کلاس RepositoryDoc.Builder استفاده کنید تا درخواست فهرست بندی را به عنوان ASYNCHRONOUS یا SYNCHRONOUS مشخص کنید:

ASYNCHRONOUS

حالت ناهمزمان منجر به تأخیر در نمایه سازی طولانی تر به خدمت می شود و سهمیه توان زیادی را برای درخواست های نمایه سازی در خود جای می دهد. حالت ناهمزمان برای نمایه سازی اولیه (Backfill) کل مخزن توصیه می شود.

SYNCHRONOUS

حالت همزمان منجر به تأخیر در نمایه سازی کوتاه تر به خدمت می شود و سهمیه توان محدود را در خود جای می دهد. حالت همزمان برای نمایه سازی به روزرسانی ها و تغییر در مخزن توصیه می شود. اگر نامشخص باشد ، حالت درخواست به SYNCHRONOUS پیش فرض می کند.

IDS کودک را در صف فهرست بندی جستجوی Cloud قرار دهید

قطعه کد زیر نشان می دهد که چگونه می توان شناسه های کودک را برای کالای والدین در حال پردازش در حال حاضر در صف پردازش قرار داد. این شناسه ها پس از فهرست بندی کالای والدین پردازش می شوند.

graphtraversalsample.java

در GitHub مشاهده کنید

// 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();

توجه: جستجوی ابر داده های متا را برای همه پرونده ها فهرست می کند. بسته به نوع پرونده یک مورد ، جستجوی ابری همچنین محتوای متن را فهرست می کند ، از جمله استفاده از تشخیص کاراکتر نوری (OCR) بر روی محتوای دست نوشته. برای لیستی از انواع فایل های پشتیبانی از استخراج متن ، برای استخراج متن به انواع فایل پشتیبانی شده مراجعه کنید.

مراحل بعدی

در اینجا چند مرحله بعدی که ممکن است انجام دهید وجود دارد:

• (اختیاری) روش close() را برای انتشار هرگونه منابع قبل از خاموش کردن پیاده سازی کنید.
• (اختیاری) با استفاده از Connector Identity SDK یک کانکتور هویت ایجاد کنید .

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

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

استراتژی سفر خود را تعیین کنید

عملکرد اصلی یک کانکتور محتوا ، عبور از یک مخزن و فهرست بندی داده های آن است. شما باید بر اساس اندازه و چیدمان داده ها در مخزن خود ، یک استراتژی سفر را اجرا کنید. در زیر سه استراتژی سفر مشترک وجود دارد:

استراتژی کامل سفر

یک استراتژی کامل مسافرتی کل مخزن را اسکن می کند و کورکورانه هر مورد را فهرست می کند. این استراتژی معمولاً در زمانی که یک مخزن کوچک دارید استفاده می شود و می توانید هر بار که فهرست می کنید ، سربار انجام یک مسیر کامل را انجام دهید.

این استراتژی سفر برای مخازن کوچک با داده های استاتیک ، غیر سلسله مراتبی مناسب است. همچنین ممکن است از این استراتژی مسافرتی استفاده کنید که تشخیص تغییر دشوار باشد یا توسط مخزن پشتیبانی نشود.

استراتژی سفر را لیست کنید

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

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

پیمایش نمودار

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

این استراتژی مناسب است اگر داده های سلسله مراتبی داشته باشید که نیاز به خزیدن داشته باشد ، مانند دایرکتوری های سری یا صفحات وب.

توجه: اصطلاحات "مورد" و "سند" در این سند و کد نمونه مترادف هستند.

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

به هر عنصر شاخصی برای جستجوی ابری به عنوان موردی در API جستجوی ابر گفته می شود. یک مورد ممکن است یک پرونده ، پوشه ، یک خط در یک پرونده CSV یا یک رکورد پایگاه داده باشد.

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

1. (اختیاری) با استفاده از items.upload برای بارگذاری پرونده های بزرگتر از 100kib برای نمایه سازی. برای پرونده های کوچکتر ، محتوا را به عنوان InlineContent با استفاده از items.index جاسازی کنید.

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/?ref_=nv_sr_1",
       "objectType": "movie"
     },
     "structuredData": {
       "object": {
         "properties": [
           {
             "name": "movieTitle",
             "textValues": {
               "values": [
                 "Titanic"
               ]
             }
           },
           {
             "name": "releaseDate",
             "dateValues": {
               "values": [
                 {
                   "year": 1997,
                   "month": 12,
                   "day": 19
                 }
               ]
             }
           },
           {
             "name": "actorName",
             "textValues": {
               "values": [
                 "Leonardo DiCaprio",
                 "Kate Winslet",
                 "Billy Zane"
               ]
             }
           },
           {
             "name": "genre",
             "enumValues": {
               "values": [
                 "Drama",
                 "Action"
               ]
             }
           },
           {
             "name": "userRating",
             "integerValues": {
               "values": [
                 8
               ]
             }
           },
           {
             "name": "mpaaRating",
             "textValues": {
               "values": [
                 "PG-13"
               ]
             }
           },
           {
             "name": "duration",
             "textValues": {
               "values": [
                 "3 h 14 min"
               ]
             }
           }
         ]
       }
     },
     "content": {
       "inlineContent": "A seventeen-year-old aristocrat falls in love with a kind but poor artist aboard the luxurious, ill-fated R.M.S. Titanic.",
       "contentFormat": "TEXT"
     },
     "version": "01",
     "itemType": "CONTENT_ITEM"
   }
   

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

برای انجام یک سفر کامل ، به طور دوره ای کل مخزن را مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً مجدداً تنظیم می کنید. برای انجام یک لیست یا نمودار نمودار ، برای کنترل تغییرات مخزن باید کد را پیاده سازی کنید.

توجه: قسمت objectType در ItemMetadata باید با نام تعریف شیء در طرح مطابقت داشته باشد. به این ترتیب ، جستجوی ابر ساختار مورد انتظار شیء را در درخواست شاخص مشخص می کند. اگر در یک درخواست نمایه سازی ، داده های ساختاری را ارسال کنید که حاوی خواصی است که در طرح فعلی ثبت نشده اند ، یا یک نوع شیء را ارائه می دهید که با نام یکی از تعاریف شیء در طرح مطابقت ندارد ، شیء یا خاصیت نادیده گرفته می شود . علاوه بر این ، اگر خواصی را با نوعی متفاوت از نوع ثبت شده در طرحواره ارسال می کنید ، جستجوی ابر در زمان نمایه سازی پاسخ خطا را برمی گرداند.

توجه: هر اتصال HTTP که مشتری شما در سربار به دست می آورد. برای کاهش سربار ، می توانید چندین تماس API را به یک درخواست HTTP اختصاص دهید. برای یادگیری نحوه کاهش سربار اتصالات HTTP ، به درخواست دسته بندی مراجعه کنید. برای یادگیری نحوه رسیدگی به بارگذاری رسانه های بزرگ ، به آپلودهای رسانه ای مستقیم و از سرگیری مراجعه کنید.

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

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

به جای استفاده از تماس های شاخص برای فهرست بندی یک مخزن کامل ، هر چند وقت یک بار ، می توانید از صف فهرست بندی Google Cloud به عنوان مکانیسمی برای ردیابی تغییرات و فقط فهرست بندی مواردی که تغییر کرده اند استفاده کنید. می توانید از درخواست های موردی استفاده کنید. برای اطلاعات بیشتر در مورد صف فهرست بندی Google Cloud ، به صف فهرست بندی Google Cloud مراجعه کنید.

برای کسب اطلاعات بیشتر در مورد API جستجوی Google Cloud ، به API Cloud Search مراجعه کنید.