یک رابط جستجو با Query API ایجاد کنید

Query API روش‌های جستجو و پیشنهادی را برای ایجاد یک رابط جستجو یا جاسازی نتایج جستجو در یک برنامه ارائه می‌کند.

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

یک رابط جستجو بسازید

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

  1. یک برنامه جستجو را پیکربندی کنید
  2. اعتبارنامه OAuth را برای برنامه ایجاد کنید
  3. فهرست را پرس و جو کنید
  4. نمایش نتایج پرس و جو

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

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

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

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

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

علاوه بر مراحل پیکربندی دسترسی به Google Cloud Search API ، همچنین باید اعتبارنامه OAuth را برای برنامه وب ایجاد کنید. نوع اعتبارنامه هایی که ایجاد می کنید بستگی به زمینه ای دارد که API در آن استفاده می شود.

از اعتبارنامه ها برای درخواست مجوز از طرف کاربر استفاده کنید. هنگام درخواست مجوز از محدوده https://www.googleapis.com/auth/cloud_search.query استفاده کنید.

برای اطلاعات بیشتر درباره گزینه‌های OAuth و کتابخانه‌های سرویس گیرنده، به [Google Identity Platform](https://developers.google.com/identity/choose-auth{: .external target="_blank"} مراجعه کنید.

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

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

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

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

{
  "query": "titanic",
  "requestOptions": {
    "searchApplicationId": "searchapplications/<search_app_id>"
  },
}

نمایش نتایج پرس و جو

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

نتایج تکمیلی را مدیریت کنید

به‌طور پیش‌فرض، جستجوی ابری نتایج تکمیلی را زمانی برمی‌گرداند که نتایج کافی برای درخواست کاربر وجود نداشته باشد. قسمت queryInterpretation در پاسخ نشان می دهد که نتایج تکمیلی چه زمانی برگردانده می شوند. اگر فقط نتایج تکمیلی برگردانده شود، InterpretationType روی REPLACE تنظیم می شود. اگر چند نتیجه برای پرس و جو اصلی همراه با نتایج تکمیلی برگردانده شود، InterpretationType روی BLEND تنظیم می شود. در هر صورت QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY .

هنگامی که برخی از نتایج تکمیلی برگردانده می شوند، متنی را برای نشان دادن بازگشت نتایج تکمیلی در نظر بگیرید. به عنوان مثال، در مورد REPLACE ، ممکن است رشته "جستجوی شما برای درخواست اصلی شما با هیچ نتیجه ای مطابقت نداشت. نمایش نتایج برای جستارهای مشابه" را نمایش دهید.

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

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

Cloud Search دو نوع «نتایج افراد» را برمی گرداند: اسناد مربوط به شخصی که نام او در پرس و جو استفاده می شود و اطلاعات کارمند برای شخصی که نامش در یک پرس و جو استفاده می شود. نوع دوم نتیجه تابعی از ویژگی جستجوی افراد در Cloud Search است و نتایج چنین پرس و جوی را می توان در قسمت structuredResults پاسخ API query پیدا کرد:

{
  "results": [...],
  "structuredResults": [{
    "person": {...}
  }]
}

تطبیق گزارش های مستقیم

تطبیق مستقیم گزارش‌ها یک ویژگی جستجوی افراد در Cloud Search است که به کاربران امکان می‌دهد گزارش‌های مستقیم یک فرد در سازمان خود را ببینند. نتیجه در فیلد structuredResults در دسترس است.

برای پرسش‌هایی درباره مدیر یک شخص یا گزارش‌های مستقیم، پاسخ دارای یک assistCardProtoHolder در structuredResults است. assistCardProtoHolder یک فیلد به نام cardType دارد که برابر با RELATED_PEOPLE_ANSWER_CARD خواهد بود. assistCardProtoHolder حاوی کارتی به نام relatedPeopleAnswerCard است که حاوی پاسخ واقعی است. شامل subject (شخصی که در پرس و جو گنجانده شده است) و relatedPeople که مجموعه افراد مرتبط با موضوع هستند. فیلد relationType مقدار MANAGER یا DIRECT_REPORTS را برمی‌گرداند.

کد زیر نمونه ای از پاسخ را برای یک پرس و جو گزارش های مستقیم منطبق نشان می دهد: 

{
  "results": [],
  "structuredResults": [{
    "assistCardProtoHolder": {
      "extensions": {
        "@type": "type.googleapis.com/enterprise.topaz.sidekick.AssistCardProto",
        "cardMetadata": {
          "cardCategory": "ANSWER"
        },
        "cardType": "RELATED_PEOPLE_ANSWER_CARD",
        "relatedPeopleAnswerCard": {
          "subject": {
            "email": "AdamStanford@psincs-test01.newjnj.com",
            "displayName": "Adam Stanford"
            "manager": {
              "email": "simonsais@psincs-test01.newjnj.com"
            }
          },
          "relatedPeople": [{
            "email": "EdgarMountainRamirez@psincs-test01.newjnj.com",
            "displayName": "Edgar Mountain Ramirez"
          }, {
            "email": "FranciscoJoseMartinez@psincs-test01.newjnj.com",
            "displayName": "Francisco Jose Martinez"
          }],
          "relationType": "DIRECT_REPORTS",
        }
      }
    }
  }]
}

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

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

  • برای خاموش کردن همه بهینه‌سازی‌ها در سطح برنامه جستجو، از جمله نتایج تکمیلی، مترادف‌ها، و اصلاحات املا، QueryInterpretationConfig.force_verbatim_mode را در برنامه‌های جستجو روی true تنظیم کنید.

  • برای خاموش کردن همه بهینه‌سازی‌ها در سطح جست‌وجو، از جمله نتایج تکمیلی، مترادف‌ها، و تصحیح املا، QueryInterpretationOptions.enableVerbatimMode را در عبارت جستجو روی true تنظیم کنید.

  • برای خاموش کردن نتایج تکمیلی در سطح برنامه جستجو، QueryInterpretationOptions.forceDisableSupplementalResults را در عبارت جستجو روی true تنظیم کنید.

  • برای خاموش کردن نتایج تکمیلی در سطح جستجو، QueryInterpretationOptions.disableSupplementalResults را در عبارت جستجو روی true تنظیم کنید.

گزیده ها را برجسته کنید

برای موارد برگردانده شده حاوی متن نمایه شده یا محتوای HTML، یک قطعه از محتوا برگردانده می شود. این محتوا به کاربران کمک می کند تا ارتباط کالای برگشتی را تعیین کنند.

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

از matchRanges برای برجسته کردن متن منطبق هنگام ارائه نتایج استفاده کنید. مثال زیر جاوا اسکریپت قطعه را به نشانه گذاری HTML با هر محدوده منطبق در یک تگ <span> تبدیل می کند.

function highlightSnippet(snippet) {
  let text = snippet.snippet;
  let formattedText = text;
  if (snippet.matchRanges) {
    let parts = [];
    let index = 0;
    for (let match of snippet.matchRanges) {
      let start = match.start || 0; // Default to 0 if omitted
      let end = match.end;
      if (index < start) { // Include any leading text before/between ranges
        parts.push(text.slice(index, start));
      }
      parts.push('<span class="highlight">');
      parts.push(text.slice(start, end));
      parts.push('</span>');
      index = end;
    }
    parts.push(text.slice(index)); // Include any trailing text after last range
    formattedText = parts.join('');
  }
  return formattedText;
}

با توجه به این قطعه:

{
  "snippet": "This is an example snippet...",
  "matchRanges": [
    {
      "start": 11,
      "end": 18
    }
  ]
}

رشته HTML حاصل به صورت زیر است: 

This is an <span class="highlight">example</span> snippet...

نمایش متادیتا

از فیلد metadata برای نمایش اطلاعات اضافی در مورد مورد برگشتی که ممکن است مربوط به کاربران باشد استفاده کنید. فیلد metadata شامل createTime و updateTime مورد و همچنین هرگونه داده ساختاریافته قابل بازگشت مرتبط با مورد است.

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

نتایج اضافی را بازیابی کنید

برای بازیابی نتایج اضافی، فیلد start در درخواست را روی افست مورد نظر تنظیم کنید. می توانید اندازه هر صفحه را با فیلد pageSize تنظیم کنید.

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

نتایج را مرتب کنید

از فیلد sortOptions برای تعیین ترتیب موارد برگشتی استفاده کنید. مقدار sortOptions یک شی با دو فیلد است:

  • operatorName - عملگر برای مرتب‌سازی ویژگی داده‌های ساخت‌یافته. برای خواص با چند عملگر، فقط می توانید با استفاده از عملگر اصلی برابری مرتب کنید.
  • sortOrder - جهت مرتب سازی، ASCENDING یا DESCENDING .

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

"sortOptions": {
  "operatorName": "priority",
  "sortOrder": "DESCENDING"
}

فیلترها را اضافه کنید

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

برای افزودن فیلترها در یک درخواست یا برنامه جستجو، فیلتر را در قسمت dataSourceRestrictions.filterOptions[] اضافه کنید.

2 راه اصلی برای فیلتر کردن بیشتر منبع داده وجود دارد:

  • فیلترهای شیء، از طریق ویژگی filterOptions[].objectType — موارد تطبیق را به نوع مشخصی که در یک طرح سفارشی تعریف شده است، محدود می کند.
  • فیلترهای ارزش - موارد تطبیق را بر اساس عملگر پرس و جو و مقدار ارائه شده محدود می کند.

فیلترهای ترکیبی امکان ترکیب فیلترهای چندگانه را در عبارات منطقی برای پرس و جوهای پیچیده تر می دهند.

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

{
  "query": "adventure",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>"
  },
  "dataSourceRestrictions": [
    {
      "source": {
        "name": "datasources/<data_source_id>"
      },
      "filterOptions": [
        {
          "objectType": "movie",
          "filter": {
            "compositeFilter": {
              "logicOperator": "AND"
              "subFilters": [
                {
                  "compositeFilter": {
                  "logicOperator": "OR"
                  "subFilters": [
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "G"
                        }
                      }
                    },
                    {
                      "valueFilter": {
                        "operatorName": "rated",
                        "value": {
                          "stringValue": "PG"
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

نتایج را با جنبه‌ها اصلاح کنید

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

جنبه ها را می توان در برنامه جستجوی شما تعریف کرد. و با تنظیمات در درخواست شما لغو می شود.

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

الگوی متقابل معمول با وجوه عبارت است از:

  1. یک پرس و جو اولیه ایجاد کنید و مشخص کنید که کدام ویژگی ها در نتایج جنبه گنجانده شود.
  2. نتایج جستجو و جنبه را ارائه دهید.
  3. کاربر یک یا چند مقدار جنبه را برای اصلاح نتایج انتخاب می کند.
  4. پرس و جو را با یک فیلتر بر اساس مقادیر انتخاب شده تکرار کنید.

به عنوان مثال، برای فعال کردن پالایش جستجوهای فیلم بر اساس سال و رتبه بندی MPAA، ویژگی facetOptions را در پرس و جو قرار دهید. 

"facetOptions": [
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "year"
  },
  {
    "sourceName": "datasources/<data_source_id>",
    "operatorName": "rated"
  }
]

نتایج وجهی با فیلدهای مبتنی بر عدد صحیح

همچنین می توانید نتایج را با فیلدهای مبتنی بر عدد صحیح تنظیم کنید. برای مثال، ممکن است یک ویژگی عدد صحیح به نام book_pages را به‌عنوان facetable علامت‌گذاری کنید تا نتایج جستجوی کتاب‌هایی با صفحات «100-200» را اصلاح کنید.

هنگامی که شما طرح فیلد ویژگی عدد صحیح خود را تنظیم می کنید، isFacetable روی true تنظیم کنید و گزینه های سطل مربوطه را به integerPropertyOptions اضافه کنید. این تضمین می کند که هر ویژگی با عدد صحیح دارای گزینه های سطل بندی پیش فرض تعریف شده است.

هنگام تعریف منطق گزینه های سطل، آرایه ای از مقادیر افزایشی را ارائه دهید که نشان دهنده محدوده است. برای مثال، اگر کاربر نهایی محدوده‌هایی را به‌عنوان 2, 5, 10, 100 مشخص کند، وجه‌های <2 ، [2-5) ، [5-10) ، [10-100) ، >=100 محاسبه می‌شوند.

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

نتایج وجهی بر اساس اندازه سند یا تاریخ

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

  • برای نمایان شدن بر اساس اندازه سند، itemsize استفاده کنید و گزینه‌های سطل را تعریف کنید.
  • برای نمایان شدن بر اساس تاریخ ایجاد سند، از createddatetimestamp استفاده کنید.
  • برای نمایان شدن بر اساس تاریخ اصلاح سند، از lastmodified استفاده کنید.

تفسیر سطل های جنبه

ویژگی facetResults در پاسخ عبارت جستجو شامل درخواست فیلتر دقیق کاربر در قسمت filter برای هر bucket است.

برای جنبه هایی که بر اساس اعداد صحیح نیستند، facetResults شامل یک ورودی برای هر ویژگی درخواستی می شود. برای هر ویژگی، فهرستی از مقادیر یا محدوده ها به نام buckets ارائه می شود. مقادیر متداول در ابتدا ظاهر می شوند.

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

پیشنهادات را اضافه کنید

از پیشنهاد API برای ارائه تکمیل خودکار درخواست‌ها بر اساس تاریخچه درخواست شخصی کاربر و همچنین مخاطبین و مجموعه اسناد آنها استفاده کنید.

به عنوان مثال، فراخوان زیر پیشنهادهایی برای عبارت جزئی jo می دهد.

{
  "query": "jo",
  "requestOptions": {
    "searchApplicationId": "<search_app_id>",
    "peoplePhotoOptions": {
      "peoplePhotoUrlSizeInPx": 32
    },
    "timeZone": "America/Denver"
  }
}

سپس می توانید پیشنهادات به دست آمده را متناسب با برنامه خود نمایش دهید.