یک رابط CSV راه اندازی کنید

این راهنما برای مدیران رابط Google Cloud Search CSV (مقادیر جدا شده با کاما) در نظر گرفته شده است، یعنی هر کسی که مسئول دانلود، پیکربندی، اجرا و نظارت بر رابط است.

این راهنما شامل دستورالعمل هایی برای انجام وظایف کلیدی مربوط به استقرار کانکتور CSV است:

• نرم افزار رابط CSV Google Cloud Search را دانلود کنید
• رابط را برای استفاده با منبع داده CSV خاص پیکربندی کنید
• کانکتور را مستقر کرده و اجرا کنید

برای درک مفاهیم موجود در این سند، باید با اصول Google Workspace، فایل‌های CSV و لیست‌های کنترل دسترسی (ACL) آشنا باشید.

نمای کلی رابط Google Cloud Search CSV

رابط CSV Cloud Search با هر فایل متنی مقادیر جدا شده با کاما (CSV) کار می کند. یک فایل CSV داده های جدولی را ذخیره می کند و هر خط از فایل یک رکورد داده است.

رابط CSV Google Cloud Search سطرهای جداگانه را از یک فایل CSV استخراج می کند و از طریق API Indexing Cloud Search در Cloud Search فهرست می کند. پس از فهرست‌بندی موفقیت‌آمیز، ردیف‌های جداگانه از فایل‌های CSV از طریق کلاینت‌های Cloud Search یا Cloud Search Query API قابل جستجو هستند. رابط CSV همچنین از کنترل دسترسی کاربران به محتوا در نتایج جستجو با استفاده از ACL پشتیبانی می کند.

رابط Google Cloud Search CSV را می توان روی لینوکس یا ویندوز نصب کرد. قبل از استقرار رابط Google Cloud Search CSV، مطمئن شوید که اجزای مورد نیاز زیر را دارید:

• جاوا JRE 1.8 روی رایانه‌ای نصب شده است که رابط Google Cloud Search CSV را اجرا می‌کند

• اطلاعات Google Workspace برای ایجاد روابط بین Google Cloud Search و منبع داده مورد نیاز است:

  • کلید خصوصی Google Workspace (که شامل شناسه حساب سرویس است)
  • شناسه منبع داده Google Workspace

  به طور معمول، سرپرست Google Workspace برای دامنه می‌تواند این اعتبارنامه‌ها را برای شما فراهم کند.

مراحل استقرار

برای استقرار رابط Google Cloud Search CSV این مراحل را دنبال کنید:

1. نرم افزار رابط Google Cloud Search CSV را نصب کنید
2. پیکربندی رابط CSV را مشخص کنید
3. دسترسی به منبع داده Google Cloud Search را پیکربندی کنید
4. دسترسی به فایل CSV را پیکربندی کنید
5. نام ستون‌ها را برای فهرست، ستون‌های کلیدی منحصربه‌فرد و ستون‌های تاریخ تعیین کنید
6. ستون هایی را برای استفاده در URL های نتایج جستجوی قابل کلیک مشخص کنید
7. اطلاعات فراداده، قالب های ستون را مشخص کنید
8. پیمایش داده ها را برنامه ریزی کنید
9. گزینه های لیست کنترل دسترسی (ACL) را مشخص کنید

1. SDK را نصب کنید

SDK را در مخزن محلی Maven خود نصب کنید.

1. مخزن SDK را از GitHub کلون کنید.

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. نسخه مورد نظر SDK را بررسی کنید:

   $ git checkout tags/v1-0.0.3

3. ساخت کانکتور:

   $ mvn package

4. فایل zip رابط را در دایرکتوری نصب محلی خود کپی کنید:

   $ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir
   $ cd installation-dir
   $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip
   $ cd google-cloudsearch-csv-connector-v1-0.0.3

2. پیکربندی رابط CSV را مشخص کنید

به‌عنوان مدیر رابط، شما رفتار رابط CSV و ویژگی‌های تعیین‌کننده پارامترها را در فایل پیکربندی کانکتور کنترل می‌کنید. پارامترهای قابل تنظیم عبارتند از:

• دسترسی به منبع داده
• محل فایل CSV
• تعاریف ستون CSV
• ستون(هایی) که یک شناسه منحصر به فرد را تعریف می کنند
• گزینه های پیمایش
• گزینه های ACL برای محدود کردن دسترسی به داده ها

برای اینکه کانکتور به درستی به یک فایل CSV دسترسی داشته باشد و محتوای مربوطه را فهرست کند، ابتدا باید فایل پیکربندی آن را ایجاد کنید.

برای ایجاد یک فایل پیکربندی:

1. یک ویرایشگر متن دلخواه خود را باز کنید و فایل پیکربندی را نام ببرید.
   همانطور که در بخش‌های زیر توضیح داده شد، جفت‌های key =value را به محتویات فایل اضافه کنید.
2. فایل پیکربندی را ذخیره و نامگذاری کنید.
   Google توصیه می‌کند که نام فایل پیکربندی را connector-config.properties بگذارید تا هیچ پارامتر خط فرمان اضافی برای اجرای کانکتور مورد نیاز نباشد.

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

برای اطمینان از اینکه کانکتور فایل پیکربندی شما را می شناسد، مسیر آن را در خط فرمان مشخص کنید. در غیر این صورت، رابط از connector-config.properties در فهرست محلی شما به عنوان نام فایل پیش فرض استفاده می کند. برای اطلاعات در مورد تعیین مسیر پیکربندی در خط فرمان، به اجرای رابط CSV Cloud Search مراجعه کنید.

3. دسترسی به منبع داده Google Cloud Search را پیکربندی کنید

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

4. پارامترهای فایل CSV را پیکربندی کنید

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

5. نام ستون ها را برای فهرست بندی و ستون های کلید یکتا مشخص کنید

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

6. ستون هایی را برای استفاده در URL های نتایج جستجوی قابل کلیک مشخص کنید

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

7. اطلاعات فراداده، قالب های ستون، کیفیت جستجو را مشخص کنید

می توانید پارامترهایی را به فایل پیکربندی اضافه کنید که مشخص می کند:

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

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

پارامترهای پیکربندی فراداده ستون‌های CSV مورد استفاده برای پر کردن ابرداده مورد را توصیف می‌کند. اگر فایل پیکربندی شامل این پارامترها نباشد، از مقادیر پیش فرض استفاده می شود. جدول زیر این پارامترها را نشان می دهد.

فرمت های زمان تاریخ

قالب‌های Datetime قالب‌های مورد انتظار در ویژگی‌های ابرداده را مشخص می‌کنند. اگر فایل پیکربندی حاوی این پارامتر نباشد، از مقادیر پیش فرض استفاده می شود. جدول زیر این پارامتر را نشان می دهد.

قالب های ستونی

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

کیفیت جستجو

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

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

8. پیمایش داده ها را برنامه ریزی کنید

پیمایش فرآیند اتصال دهنده برای کشف محتوا از منبع داده، در این مورد، یک فایل CSV است. همانطور که رابط CSV اجرا می شود، ردیف های یک فایل CSV را طی می کند و هر ردیف را از طریق Indexing API به Cloud Search فهرست می کند.

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

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

9. گزینه های Access Control List (ACL) را مشخص کنید

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

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

کانکتور به فعال بودن ACL های پیش فرض در فایل پیکربندی متکی است. برای فعال کردن ACLهای پیش‌فرض، defaultAcl.mode روی حالتی غیر از none تنظیم کنید و آن را با defaultAcl.*

تعریف طرحواره

جستجوی ابری امکان نمایه سازی و ارائه محتوای ساختاریافته و بدون ساختار را فراهم می کند. به منظور پشتیبانی از پرس و جوهای داده های ساختاریافته در داده های خود، باید Schema را برای منبع داده خود تنظیم کنید .

پس از تعریف، CSV Connector می تواند شمای تعریف شده را برای ساخت درخواست های نمایه سازی ارجاع دهد. برای ارائه یک مثال گویا، اجازه دهید یک فایل CSV حاوی اطلاعاتی درباره فیلم ها در نظر بگیریم.

بیایید فرض کنیم، فایل CSV ورودی دارای محتوای زیر است.

1. شناسه فیلم
2. عنوان فیلم
3. توضیحات
4. سال
5. تاریخ انتشار
6. بازیگران (مقادیر متعدد با کاما (،) از هم جدا شده اند)
7. ژانر (مقدارهای چندگانه)
8. رتبه بندی ها

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

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "actors",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "textPropertyOptions": {
            "operatorOptions": {
              "operatorName": "actor"
            }
          }
        },
        {
          "name": "releaseDate",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "datePropertyOptions": {
            "operatorOptions": {
              "operatorName": "released",
              "lessThanOperatorName": "releasedbefore",
              "greaterThanOperatorName": "releasedafter"
            }
          }
        },
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "textPropertyOptions": {
            "retrievalImportance": {
              "importance": "HIGHEST"
            },
            "operatorOptions": {
              "operatorName": "title"
            }
          }
        },
        {
          "name": "genre",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "enumPropertyOptions": {
            "operatorOptions": {
              "operatorName": "genre"
            },
            "possibleValues": [
              {
                "stringValue": "Action"
              },
              {
                "stringValue": "Documentary"
              },
              {
                "stringValue": "Drama"
              },
              {
                "stringValue": "Crime"
              },
              {
                "stringValue": "Sci-fi"
              }
            ]
          }
        },
        {
          "name": "userRating",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": true,
          "integerPropertyOptions": {
            "orderedRanking": "ASCENDING",
            "maximumValue": "10",
            "operatorOptions": {
              "operatorName": "score",
              "lessThanOperatorName": "scorebelow",
              "greaterThanOperatorName": "scoreabove"
            }
          }
        }
      ]
    }
  ]
}

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

فایل پیکربندی مثال زیر جفت‌های پارامتر key=value نشان می‌دهد که رفتار یک کانکتور نمونه را تعریف می‌کند.

# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json

# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle

# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE

#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true

برای توضیحات دقیق هر پارامتر، به مرجع پارامترهای پیکربندی مراجعه کنید.

رابط CSV Cloud Search را اجرا کنید

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

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

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