یک طرحواره ایجاد و ثبت کنید

طرحواره جستجوی ابری Google یک ساختار JSON است که اشیاء، ویژگی‌ها و گزینه‌های مورد استفاده در فهرست‌بندی و جستجوی داده‌های شما را تعریف می‌کند. رابط محتوای شما داده ها را از مخزن شما می خواند و بر اساس طرحواره ثبت شده شما، داده ها را ساختار و فهرست بندی می کند.

شما می توانید با ارائه یک شی طرح JSON به API و سپس ثبت آن، یک طرحواره ایجاد کنید. قبل از اینکه بتوانید داده های خود را فهرست کنید، باید برای هر یک از مخازن خود یک شی طرح ثبت کنید.

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

یک طرحواره ایجاد کنید

در زیر لیستی از مراحل استفاده شده برای ایجاد طرحواره جستجوی ابری شما آمده است:

1. رفتار مورد انتظار کاربر را شناسایی کنید
2. یک منبع داده را راه اندازی کنید
3. یک طرحواره ایجاد کنید
4. طرح واره نمونه کامل
5. طرحواره خود را ثبت کنید
6. داده های خود را فهرست کنید
7. طرحواره خود را تست کنید
8. طرحواره خود را تنظیم کنید

رفتار مورد انتظار کاربر را شناسایی کنید

پیش بینی انواع پرس و جوهایی که کاربران شما ایجاد می کنند به هدایت استراتژی شما برای ایجاد طرح شما کمک می کند.

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

برای تعریف طرحواره خود به گونه ای که الگوهای رفتاری کاربر شما را منعکس کند، این وظایف را در نظر بگیرید:

1. مجموعه متنوعی از پرس و جوهای مورد نظر از کاربران مختلف را ارزیابی کنید.
2. اشیایی را که ممکن است در کوئری ها استفاده شوند، شناسایی کنید. اشیا مجموعه‌ای منطقی از داده‌های مرتبط هستند، مانند یک فیلم در پایگاه داده فیلم‌ها.
3. خصوصیات و مقادیری که شی را تشکیل می دهند و ممکن است در کوئری ها استفاده شوند را شناسایی کنید. ویژگی ها ویژگی های قابل نمایه سازی شی هستند. آنها می توانند شامل مقادیر اولیه یا اشیاء دیگر باشند. به عنوان مثال، یک شی فیلم ممکن است دارای ویژگی هایی مانند عنوان فیلم و تاریخ انتشار به عنوان مقادیر اولیه باشد. شی فیلم همچنین ممکن است دارای اشیاء دیگری باشد، مانند اعضای بازیگر، که ویژگی‌های خاص خود را دارند، مانند نام یا نقش آنها.
4. مقادیر معتبر نمونه برای خواص را شناسایی کنید. مقادیر ، داده های واقعی نمایه شده برای یک ویژگی هستند. برای مثال، عنوان یک فیلم در پایگاه داده شما ممکن است "Raiders of the Lost Ark" باشد.
5. گزینه های مرتب سازی و رتبه بندی مورد نظر کاربران خود را تعیین کنید. برای مثال، هنگام جستجوی فیلم‌ها، کاربران ممکن است بخواهند به ترتیب زمانی و رتبه‌بندی بر اساس رتبه‌بندی مخاطبان مرتب شوند و نیازی به مرتب‌سازی بر اساس حروف الفبا بر اساس عنوان نداشته باشند.
6. (اختیاری) در نظر بگیرید که یکی از ویژگی های شما زمینه خاص تری را نشان می دهد که جستجوها ممکن است در آن انجام شوند، مانند نقش شغلی کاربران یا بخش، به طوری که پیشنهادات تکمیل خودکار براساس زمینه ارائه شود. به عنوان مثال، برای افرادی که در پایگاه داده فیلم ها جستجو می کنند، کاربران ممکن است فقط به ژانر خاصی از فیلم ها علاقه مند باشند. کاربران تعریف می کنند که می خواهند جستجوهایشان به چه سبکی بازگردد، احتمالاً به عنوان بخشی از نمایه کاربری خود. سپس، هنگامی که کاربر شروع به تایپ کردن درخواستی از فیلم‌ها می‌کند، تنها فیلم‌هایی در ژانر دلخواه او، مانند «فیلم‌های اکشن» به عنوان بخشی از پیشنهادات تکمیل خودکار پیشنهاد می‌شوند.
7. فهرستی از این اشیاء، خواص و مقادیر نمونه تهیه کنید که می توانند در جستجوها استفاده شوند. (برای جزئیات در مورد نحوه استفاده از این لیست، به بخش تعریف گزینه های عملگر مراجعه کنید.)

منبع داده خود را مقداردهی اولیه کنید

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

نتایج جستجوی کاربر از منبع داده بازگردانده می شود. هنگامی که کاربر روی یک نتیجه جستجو کلیک می کند، جستجوی ابری کاربر را با استفاده از URL ارائه شده در درخواست نمایه سازی به مورد واقعی هدایت می کند.

اشیاء خود را تعریف کنید

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

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

شکل 1 اشیاء فیلم و شخص و ویژگی های مرتبط را نشان می دهد.

طرحواره جستجوی ابری اساساً فهرستی از عبارات تعریف شی است که در تگ objectDefinitions تعریف شده است. قطعه طرح زیر عبارات objectDefinitions را برای اشیاء طرحواره فیلم و شخص نشان می دهد.

{
  "objectDefinitions": [
    {
      "name": "movie",
      ...
    },
    {
      "name": "person",
      ...
    }
  ]
}

هنگامی که یک شی طرحواره را تعریف می کنید، یک name برای شی ارائه می دهید که باید در بین تمام اشیاء دیگر در طرح منحصر به فرد باشد. معمولاً از یک مقدار name استفاده می کنید که شی را توصیف می کند، مانند movie برای یک شی فیلم. سرویس طرحواره از فیلد name به عنوان شناسه کلید برای اشیاء قابل نمایه سازی استفاده می کند. برای اطلاعات بیشتر در مورد فیلد name ، به تعریف شی مراجعه کنید.

خصوصیات شی را تعریف کنید

همانطور که در مرجع ObjectDefinition مشخص شده است، نام شیء با مجموعه ای از options و لیستی از propertyDefinitions دنبال می شود. options می‌توانند بیشتر از freshnessOptions و displayOptions باشند. freshnessOptions برای تنظیم رتبه بندی جستجو بر اساس تازگی یک مورد استفاده می شود. displayOptions برای تعیین اینکه آیا برچسب‌ها و ویژگی‌های خاصی در نتایج جستجو برای یک شی نمایش داده می‌شوند یا نه استفاده می‌شود.

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

قطعه زیر شی movie را با دو ویژگی نشان می دهد: movieTitle و releaseDate .

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isWildcardSearchable": true,
          "textPropertyOptions": {
            "retrievalImportance": { "importance": "HIGHEST" },
            "operatorOptions": {
              "operatorName": "title"
            }
          },
          "displayOptions": {
            "displayLabel": "Title"
          }
        },
        {
          "name": "releaseDate",
          "isReturnable": true,
          "isSortable": true,
          "datePropertyOptions": {
            "operatorOptions": {
              "operatorName": "released",
              "lessThanOperatorName": "releasedbefore",
              "greaterThanOperatorName": "releasedafter"
            }
          },
          "displayOptions": {
            "displayLabel": "Release date"
          }
      ...
      ]
    }
  ]
}

PropertyDefinition شامل موارد زیر است:

• یک رشته name
• فهرستی از گزینه‌های نوع آگنوستیک، مانند isReturnable در قطعه قبلی.
• یک نوع و گزینه‌های نوع خاص مرتبط با آن، مانند textPropertyOptions و retrievalImportance در قطعه قبلی.
• یک operatorOptions که نحوه استفاده از ویژگی را به عنوان اپراتور جستجو توصیف می کند.
• یک یا چند displayOptions ، مانند displayLabel در قطعه قبلی.

name یک ویژگی باید در داخل شی حاوی منحصر به فرد باشد، اما همان نام را می توان در اشیاء و اشیاء فرعی دیگر استفاده کرد. در شکل 1، عنوان و تاریخ اکران فیلم دو بار تعریف شده است: یک بار در شی movie و بار دیگر در زیر شی filmography شی person . این طرح از فیلد movieTitle مجددا استفاده می کند تا طرحواره بتواند از دو نوع رفتار جستجو پشتیبانی کند:

• نمایش نتایج فیلم زمانی که کاربران عنوان یک فیلم را جستجو می کنند.
• هنگامی که کاربران عنوان فیلمی را که یک بازیگر در آن بازی کرده است جستجو می‌کنند، نتایج افراد را نشان دهید.

به طور مشابه، طرح از فیلد releaseDate مجدداً استفاده می کند زیرا برای دو فیلد movieTitle معنای یکسانی دارد.

در توسعه طرح خود، در نظر بگیرید که چگونه مخزن شما ممکن است دارای فیلدهای مرتبطی باشد که حاوی داده هایی است که می خواهید بیش از یک بار در طرح خود اعلام کنید.

گزینه های type-agnostic را اضافه کنید

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

• isReturnable - نشان می دهد که آیا ویژگی داده هایی را شناسایی می کند که باید از طریق Query API در نتایج جستجو برگردانده شوند. تمام ویژگی های فیلم نمونه قابل بازگشت هستند. خواص غیر قابل بازگشت را می توان برای جستجو یا رتبه بندی نتایج بدون بازگرداندن به کاربر استفاده کرد.
• isRepeatable - نشان می دهد که آیا چندین مقدار برای ویژگی مجاز است یا خیر. به عنوان مثال، یک فیلم فقط یک تاریخ اکران دارد اما می تواند چندین بازیگر داشته باشد.
• isSortable - نشان می دهد که می توان از ویژگی برای مرتب سازی استفاده کرد. این نمی تواند برای خواصی که قابل تکرار هستند صادق باشد. به عنوان مثال، نتایج فیلم ممکن است بر اساس تاریخ انتشار یا رتبه بندی مخاطبان مرتب شوند.
• isFacetable - نشان می دهد که این ویژگی می تواند برای تولید جنبه ها استفاده شود. یک جنبه برای اصلاح نتایج جستجو استفاده می شود که به موجب آن کاربر نتایج اولیه را می بیند و سپس معیارها یا جنبه هایی را برای اصلاح بیشتر آن نتایج اضافه می کند. این گزینه برای خواصی که نوع آنها شی است نمی تواند درست باشد و برای تنظیم این گزینه isReturnable باید true باشد. در نهایت، این گزینه فقط برای ویژگی های enum، boolean و text پشتیبانی می شود. به عنوان مثال، در طرح نمونه خود، ممکن است genre ، actorName ، userRating ، و mpaaRating را به صورت facetable بسازیم تا بتوانیم از آنها برای اصلاح تعاملی نتایج جستجو استفاده کنیم.
• isWildcardSearchable نشان می دهد که کاربران می توانند جستجوی wildcard را برای این ویژگی انجام دهند. این گزینه فقط در ویژگی های متن موجود است. نحوه عملکرد جستجوی حروف عام در فیلد متنی به مقدار تنظیم شده در قسمت exactMatchWithOperator بستگی دارد. اگر exactMatchWithOperator روی true تنظیم شود، مقدار متن به عنوان یک مقدار اتمی نشانه گذاری می شود و یک جستجوی عام در برابر آن انجام می شود. به عنوان مثال، اگر مقدار متن science-fiction باشد، یک پرس و جو با حروف عام science-* با آن مطابقت دارد. اگر exactMatchWithOperator روی false تنظیم شود، مقدار متن نشانه گذاری می شود و یک جستجوی عام برای هر نشانه انجام می شود. به عنوان مثال، اگر مقدار متن "علمی-تخیلی" باشد، علامت عام پرس و جوهای sci* یا fi* با آیتم مطابقت دارد، اما science-* با آن مطابقت ندارد.

این پارامترهای عملکرد جستجوی عمومی همه مقادیر بولی هستند. همه آنها دارای مقدار پیش فرض false هستند و برای استفاده باید روی true تنظیم شوند.

جدول زیر پارامترهای بولی را نشان می دهد که برای تمام ویژگی های شی movie روی true تنظیم شده اند:

ویژگی	isReturnable	isRepeatable	isSortable	isFacetable	isWildcardSearchable
movieTitle	درست است، واقعی				درست است، واقعی
releaseDate	درست است، واقعی		درست است، واقعی
genre	درست است، واقعی	درست است، واقعی		درست است، واقعی
duration	درست است، واقعی
actorName	درست است، واقعی	درست است، واقعی		درست است، واقعی	درست است، واقعی
userRating	درست است، واقعی		درست است، واقعی
mpaaRating	درست است، واقعی			درست است، واقعی

هر دو genre و actorName isRepeatable روی true تنظیم شده اند زیرا یک فیلم ممکن است به بیش از یک ژانر تعلق داشته باشد و معمولاً بیش از یک بازیگر دارد. اگر یک ویژگی قابل تکرار باشد یا در یک شی فرعی تکرارپذیر وجود داشته باشد، قابل مرتب سازی نیست.

نوع را تعریف کنید

بخش مرجع PropertyDefinition چندین xxPropertyOptions را فهرست می‌کند که xx یک نوع خاص است، مانند boolean . برای تنظیم نوع داده ویژگی، باید شی نوع داده مناسب را تعریف کنید. تعریف یک شی از نوع داده برای یک ویژگی، نوع داده آن ویژگی را تعیین می کند. به عنوان مثال، تعریف textPropertyOptions برای ویژگی movieTitle نشان می دهد که عنوان فیلم از نوع متن است. قطعه زیر ویژگی movieTitle را با textPropertyOptions که نوع داده را تنظیم می کند نشان می دهد.

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    ...
  },
  ...
},

یک ویژگی ممکن است فقط یک نوع داده مرتبط داشته باشد. برای مثال، در طرح فیلم ما، releaseDate فقط می‌تواند یک تاریخ (مثلاً 2016-01-13 ) یا یک رشته (مثلاً January 13, 2016 ) باشد، اما نه هر دو.

در اینجا اشیاء نوع داده مورد استفاده برای مشخص کردن انواع داده ها برای خصوصیات در طرحواره فیلم نمونه آمده است:

ویژگی	شی از نوع داده
movieTitle	textPropertyOptions
releaseDate	datePropertyOptions
genre	enumPropertyOptions
duration	textPropertyOptions
actorName	textPropertyOptions
userRating	integerPropertyOptions
mpaaRating	textPropertyOptions

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

گزینه های نوع خاص را پیکربندی کنید

بخش مرجع PropertyDefinition به گزینه های هر نوع پیوند می دهد. اکثر گزینه‌های نوع خاص اختیاری هستند، به جز لیستی از possibleValues ​​در enumPropertyOptions . علاوه بر این، گزینه orderedRanking به شما امکان می دهد مقادیر را نسبت به یکدیگر رتبه بندی کنید. قطعه زیر ویژگی movieTitle را با textPropertyOptions که نوع داده را تنظیم می کند و با گزینه retrievalImportance نوع خاص را نشان می دهد.

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    ...
  },
  ...
}

در اینجا گزینه های نوع خاص مورد استفاده در طرح نمونه آمده است:

ویژگی	تایپ کنید	گزینه های نوع خاص
movieTitle	textPropertyOptions	retrievalImportance
releaseDate	datePropertyOptions
genre	enumPropertyOptions
duration	textPropertyOptions
actorName	textPropertyOptions
userRating	integerPropertyOptions	orderedRanking , maximumValue
mpaaRating	textPropertyOptions

گزینه های اپراتور را تعریف کنید

علاوه بر گزینه‌های نوع خاص، هر نوع دارای مجموعه‌ای از operatorOptions اختیاری است. این گزینه‌ها نحوه استفاده از ویژگی را به عنوان یک عملگر جستجو توصیف می‌کنند. قطعه زیر ویژگی movieTitle را با textPropertyOptions که نوع داده را تنظیم می‌کند و گزینه‌های نوع خاص retrievalImportance و operatorOptions را نشان می‌دهد.

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    "operatorOptions": {
      "operatorName": "title"
    }
  },
  ...
}

هر operatorOptions یک operatorName دارد، مانند title movieTitle . نام اپراتور اپراتور جستجوی ملک است. اپراتور جستجو پارامتر واقعی است که انتظار دارید کاربران هنگام محدود کردن جستجو از آن استفاده کنند. به عنوان مثال، برای جستجوی فیلم ها بر اساس عنوان آنها، کاربر title:movieName تایپ می کند، جایی که movieName نام یک فیلم است.

لازم نیست نام اپراتور با نام دارایی یکسان باشد. در عوض، باید از نام های اپراتور استفاده کنید که منعکس کننده رایج ترین کلمات استفاده شده توسط کاربران در سازمان شما باشد. به عنوان مثال، اگر کاربران شما عبارت "name" را به جای "عنوان" برای عنوان فیلم ترجیح می دهند، نام اپراتور باید روی "name" تنظیم شود.

شما می توانید از یک نام اپراتور برای چندین ویژگی استفاده کنید تا زمانی که همه ویژگی ها به یک نوع تجزیه و تحلیل شوند. هنگام استفاده از یک نام اپراتور مشترک در طول یک پرس و جو، تمام ویژگی هایی که از آن نام اپراتور استفاده می کنند بازیابی می شوند. برای مثال، فرض کنید شی فیلم دارای ویژگی plotSummary و plotSynopsis است و هر یک از این ویژگی ها دارای یک operatorName of plot . تا زمانی که هر دوی این خصوصیات متنی هستند ( textPropertyOptions )، یک پرس و جو با استفاده از عملگر جستجوی plot هر دو را بازیابی می کند.

علاوه بر operatorName ، ویژگی هایی که قابل مرتب سازی هستند می توانند دارای فیلدهای lessThanOperatorName و greaterThanOperatorName در operatorOptions باشند. کاربران می توانند از این گزینه ها برای ایجاد پرس و جو بر اساس مقایسه با مقدار ارسال شده استفاده کنند.

در نهایت، textOperatorOptions دارای یک قسمت exactMatchWithOperator در operatorOptions است. اگر exactMatchWithOperator را روی true تنظیم کنید، رشته query باید با کل مقدار ویژگی مطابقت داشته باشد، نه اینکه صرفاً در متن یافت شود. مقدار متن به عنوان یک مقدار اتمی در جستجوهای اپراتور و تطبیق جنبه ها در نظر گرفته می شود.

برای مثال، فهرست بندی اشیاء Book یا Movie با ویژگی های ژانر را در نظر بگیرید. ژانرها می توانند شامل «علمی-تخیلی»، «علمی» و «تخیلی» باشند. با تنظیم exactMatchWithOperator روی false یا حذف شده، جستجوی یک ژانر یا انتخاب جنبه "علمی" یا "تخیلی" نیز نتایجی را برای "علمی-تخیلی" نشان می دهد زیرا متن نشانه گذاری می شود و نشانه های "علمی" و "تخیلی" وجود دارد. در «علمی-تخیلی». وقتی exactMatchWithOperator true باشد، متن به عنوان یک نشانه واحد در نظر گرفته می شود، بنابراین نه "علم" و نه "تخیلی" با "علمی تخیلی" مطابقت ندارند.

(اختیاری) بخش displayOptions را اضافه کنید

یک بخش displayOptions اختیاری در انتهای هر بخش propertyDefinition وجود دارد. این بخش شامل یک رشته displayLabel است. displayLabel یک برچسب متنی توصیه شده و کاربرپسند برای ملک است. اگر ویژگی برای نمایش با استفاده از ObjectDisplayOptions پیکربندی شده باشد، این برچسب در جلوی ویژگی نمایش داده می شود. اگر ویژگی برای نمایش پیکربندی شده باشد و displayLabel تعریف نشده باشد، فقط مقدار ویژگی نمایش داده می شود.

قطعه زیر ویژگی movieTitle را با displayLabel تنظیم شده روی "Title" نشان می دهد.

{
  "name": "movieTitle",
  "isReturnable": true,
  "isWildcardSearchable": true,
  "textPropertyOptions": {
    "retrievalImportance": { "importance": "HIGHEST" },
    "operatorOptions": {
       "operatorName": "title"
    }
},
  "displayOptions": {
    "displayLabel": "Title"
  }
},

در زیر مقادیر displayLabel برای همه خصوصیات شی movie در طرح نمونه آمده است:

ویژگی	displayLabel
movieTitle	Title
releaseDate	Release date
genre	Genre
duration	Run length
actorName	Actor
userRating	Audience score
mpaaRating	MPAA rating

(اختیاری) بخش suggestionFilteringOperators[] را اضافه کنید

در انتهای هر بخش propertyDefinition یک بخش suggestionFilteringOperators[] اختیاری وجود دارد. از این بخش برای تعریف ویژگی مورد استفاده برای فیلتر کردن پیشنهادات تکمیل خودکار استفاده کنید. برای مثال، ممکن است اپراتور genre را برای فیلتر کردن پیشنهادات بر اساس ژانر فیلم ترجیحی کاربر تعریف کنید. سپس، هنگامی که کاربر عبارت جستجوی خود را تایپ می کند، فقط آن فیلم هایی که با ژانر دلخواه او مطابقت دارند به عنوان بخشی از پیشنهادات تکمیل خودکار نمایش داده می شوند.

طرحواره خود را ثبت کنید

برای بازگرداندن داده های ساختاریافته از جستارهای جستجوی ابری، باید طرح واره خود را در سرویس طرحواره جستجوی ابری ثبت کنید. ثبت یک طرحواره به شناسه منبع داده ای نیاز دارد که در مرحله Initialize a data source به دست آورده اید.

با استفاده از شناسه منبع داده، یک درخواست UpdateSchema برای ثبت طرح خود صادر کنید.

همانطور که در صفحه مرجع UpdateSchema توضیح داده شده است، درخواست HTTP زیر را برای ثبت طرح خود صادر کنید:

PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema

متن درخواست شما باید شامل موارد زیر باشد:

{
  "validateOnly": // true or false,
  "schema": {
    // ... Your complete schema object ...
  }
}

از گزینه validateOnly برای تست اعتبار طرحواره خود بدون ثبت واقعی آن استفاده کنید.

داده های خود را فهرست کنید

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

با استفاده از طرح فیلم، یک درخواست نمایه سازی REST API برای یک فیلم به شکل زیر است:

{
  "name": "datasource/<data_source_id>/items/titanic",
  "acl": {
    "readers": [
      {
        "gsuitePrincipal": {
          "gsuiteDomain": true
        }
      }
    ]
  },
  "metadata": {
    "title": "Titanic",
    "sourceRepositoryUrl": "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"
}

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

همچنین توجه داشته باشید که چگونه نمایه‌سازی ویژگی طرحواره releaseDate از ویژگی‌های فرعی year ، month و day که به ارث می‌برد استفاده می‌کند، زیرا به عنوان یک نوع داده date با استفاده از datePropertyOptions برای تعریف آن تعریف می‌شود. با این حال، از آنجایی که year ، month و day در طرحواره تعریف نشده‌اند، نمی‌توانید یکی از آن ویژگی‌ها (به عنوان مثال، year ) را به صورت جداگانه جستجو کنید.

و همچنین توجه داشته باشید که چگونه ویژگی تکرارپذیر actorName با استفاده از لیستی از مقادیر ایندکس می شود.

شناسایی مشکلات احتمالی نمایه سازی

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

• درخواست نمایه سازی شما حاوی یک شی طرح یا نام دارایی است که در سرویس طرحواره ثبت نشده است. این مشکل باعث می شود که ویژگی یا شی نادیده گرفته شود.

• درخواست نمایه سازی شما دارای ویژگی با مقدار نوع متفاوت از نوع ثبت شده در طرح است. این مشکل باعث می شود که Cloud Search در زمان نمایه سازی خطایی را برگرداند.

طرح واره خود را با چندین نوع پرس و جو آزمایش کنید

قبل از اینکه طرح خود را برای یک مخزن داده تولیدی بزرگ ثبت کنید، آزمایش را با مخزن داده های آزمایشی کوچکتر در نظر بگیرید. آزمایش با یک مخزن آزمون کوچکتر به شما این امکان را می دهد که به سرعت تغییراتی را در طرح خود انجام دهید و داده های نمایه شده را حذف کنید، بدون اینکه تأثیری بر شاخص بزرگتر یا شاخص تولید موجود داشته باشد. برای مخزن داده‌های آزمایشی، یک ACL ایجاد کنید که فقط یک کاربر آزمایشی را مجاز می‌کند تا سایر کاربران این داده‌ها را در نتایج جستجو نبینند.

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

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

با یک پرس و جو عمومی تست کنید

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

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

افزودن یک عملگر به پرس و جو، نتایج را به مواردی محدود می کند که با مقدار عملگر مطابقت دارند. برای مثال، ممکن است بخواهید از اپراتور actor برای یافتن همه فیلم‌هایی که یک بازیگر خاص در آن نقش آفرینی می‌کنند، استفاده کنید. با استفاده از یک رابط جستجو، می‌توانید این درخواست عملگر را به سادگی با تایپ کردن یک جفت operator=value ، مانند "actor:Zane" و فشار دادن Return انجام دهید. همه فیلم‌هایی که زین به عنوان بازیگر در آن حضور دارد باید در نتایج جستجو برگردانده شوند.

طرحواره خود را تنظیم کنید

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

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

نمایه سازی مجدد پس از تغییر طرحواره

تغییر هر یک از مقادیر زیر در طرح شما نیازی به فهرست مجدد داده های خود ندارد . شما به سادگی می توانید یک درخواست UpdateSchema جدید ارسال کنید و ایندکس شما به کار خود ادامه خواهد داد:

• نام اپراتورها
• مقادیر حداقل و حداکثر عدد صحیح
• رتبه بندی به ترتیب عدد صحیح و تعداد.
• گزینه های تازگی
• گزینه های نمایش

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

• افزودن یا حذف یک ویژگی یا شیء جدید
• تغییر isReturnable , isFacetable , or isSortable از false به true .

شما باید isFacetable یا isSortable را فقط در صورتی true تنظیم کنید که مورد استفاده و نیاز واضحی داشته باشید.

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

تغییرات اموال غیر مجاز

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

• نوع داده املاک
• نام ملک.
• تنظیمات exactMatchWithOperator .
• retrievalImportance تنظیم اهمیت.

با این حال، راهی برای دور زدن این محدودیت وجود دارد.

یک تغییر طرح واره پیچیده ایجاد کنید

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

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

مراحل زیر نحوه تغییر نوع داده یا نام یک ویژگی را نشان می دهد:

1. یک ویژگی جدید به تعریف شی در طرحواره خود اضافه کنید. از نامی متفاوت از ویژگی مورد نظر برای تغییر استفاده کنید.
2. درخواست UpdateSchema را با تعریف جدید صادر کنید. به یاد داشته باشید که کل طرحواره، از جمله ویژگی جدید و قدیمی را در درخواست ارسال کنید.

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

   1. در طول نمایه سازی backfill، برای جلوگیری از رفتار ناسازگار، ویژگی جدید و پیش فرض را به ویژگی قدیمی بررسی کنید.
   2. پس از تکمیل backfill، کوئری های آزمایشی را برای تأیید اجرا کنید.

4. اموال قدیمی را حذف کنید. درخواست UpdateSchema دیگری بدون نام دارایی قدیمی صادر کنید و استفاده از نام دارایی قدیمی را در درخواست‌های نمایه‌سازی آینده متوقف کنید.

5. هرگونه استفاده از دارایی قدیمی را به ملک جدید منتقل کنید. به عنوان مثال، اگر نام ویژگی را از سازنده به نویسنده تغییر دهید، باید کد درخواست خود را به روز کنید تا از نویسنده در جایی که قبلاً به خالق ارجاع داده است استفاده کنید.

Cloud Search رکوردی از هر ویژگی یا شی حذف شده را به مدت 30 روز نگه می دارد تا از هرگونه استفاده مجدد که منجر به نتایج نمایه سازی غیرمنتظره می شود محافظت کند. در طی این 30 روز، شما باید از هرگونه استفاده از شی یا ویژگی حذف شده، از جمله حذف آنها از درخواست های فهرست آینده، مهاجرت کنید. این تضمین می کند که اگر بعداً تصمیم به بازگرداندن آن ویژگی یا شیء گرفتید، می توانید این کار را به گونه ای انجام دهید که صحت شاخص شما حفظ شود.

محدودیت های اندازه را بشناسید

Cloud Search محدودیت هایی را بر اندازه اشیاء داده های ساخت یافته و طرحواره ها اعمال می کند. این محدودیت ها عبارتند از:

• حداکثر تعداد اشیاء سطح بالا 10 شی است.
• حداکثر عمق یک سلسله مراتب داده های ساخت یافته 10 سطح است.
• تعداد کل فیلدهای یک شی محدود به 1000 است که شامل تعداد فیلدهای اولیه به اضافه مجموع تعداد فیلدهای هر شیء تو در تو می شود.

مراحل بعدی

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

1. یک رابط جستجو برای آزمایش طرحواره خود ایجاد کنید.

2. طرحواره خود را برای بهبود کیفیت جستجو تنظیم کنید.

3. یک طرح واره برای تفسیر بهینه پرس و جو ساختار دهید .

4. بیاموزید که چگونه از طرح _dictionaryEntry برای تعریف مترادف عباراتی که معمولا در شرکت شما استفاده می شود استفاده کنید. برای استفاده از طرح _dictionaryEntry ، به تعریف مترادف ها مراجعه کنید.

5. یک رابط ایجاد کنید.