- طلب HTTP
- نص الطلب
- نص الاستجابة
- نطاقات التفويض
- QueryInterpretationOptions
- QueryInterpretation
- QueryInterpretation.InterpretationType
- QueryInterpretation.Reason
- SearchResult
- المقتطف
- MatchRange
- البيانات الوصفية
- ResultDisplayMetadata
- ResultDisplayMetadata.ResultDisplayLine
- ResultDisplayMetadata.ResultDisplayField:
- ResultDebugInfo
- StructuredResult
- SpellResult
- FacetResult
- FacetBucket
- ResponseDebugInfo
- ErrorInfo
- ErrorMessage
- ResultCounts
- SourceResultCount
- جرِّبه الآن
توفّر واجهة برمجة تطبيقات طلبات البحث في Cloud Search طريقة بحث تعرض النتائج الأكثر صلة بطلب بحث المستخدم. يمكن أن تأتي النتائج من تطبيقات Google Workspace، مثل Gmail أو Google Drive، أو من بيانات تمت فهرستها من جهة خارجية.
ملاحظة: تتطلّب واجهة برمجة التطبيقات هذه توفّر حساب مستخدم نهائي عادي للتنفيذ. لا يمكن لحساب الخدمة تنفيذ طلبات البيانات من واجهة برمجة التطبيقات لطلب البحث مباشرةً. ولاستخدام حساب خدمة لتنفيذ الطلبات، عليك إعداد تفويض مرجع على مستوى نطاق Google Workspace.
طلب HTTP
POST https://cloudsearch.googleapis.com/v1/query/search
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "requestOptions": { object ( |
الحقول | |
---|---|
requestOptions |
خيارات الطلب، مثل تطبيق البحث والمنطقة الزمنية للمستخدم. |
query |
سلسلة طلب البحث الأولية الاطّلاع على عوامل تشغيل البحث المتوافقة في تضييق نطاق البحث باستخدام عوامل التشغيل |
pageSize |
الحدّ الأقصى لعدد نتائج البحث التي يمكن عرضها في صفحة واحدة. القيم الصالحة تتراوح بين 1 و100، بما في ذلك القيمتان. القيمة التلقائية هي 10. الحد الأدنى للقيمة هو 50 عندما يتم طلب نتائج تتجاوز 2000. |
start |
فهرس البدء للنتائج. |
dataSourceRestrictions[] |
المصادر المطلوب استخدامها لطلب البحث. وفي حال عدم تحديد ذلك، سيتم استخدام جميع مصادر البيانات من تطبيق البحث الحالي. |
facetOptions[] |
|
sortOptions |
خيارات فرز نتائج البحث |
queryInterpretationOptions |
لتفسير طلب بحث المستخدم. |
contextAttributes[] |
سمات السياق للطلب الذي سيتم استخدامه لتعديل ترتيب نتائج البحث. الحد الأقصى لعدد العناصر هو 10. |
نص الاستجابة
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
رد واجهة برمجة تطبيقات البحث.
تمثيل JSON |
---|
{ "queryInterpretation": { object ( |
الحقول | |
---|---|
queryInterpretation |
نتيجة تفسير طلب بحث المستخدم فارغة في حال إيقاف تفسير طلب البحث. |
results[] |
نتائج من طلب بحث |
structuredResults[] |
نتائج منظَّمة لطلب بحث المستخدم ولا يتم احتساب هذه النتائج ضمن pageSize. |
spellResults[] |
تهجئة مقترحة لطلب البحث. |
facetResults[] |
نتائج واجهات متكرّرة |
hasMoreResults |
ما إذا كان هناك المزيد من نتائج البحث المطابقة لطلب البحث. |
debugInfo |
تصحيح الأخطاء في معلومات الرد. |
errorInfo |
معلومات خطأ حول الردّ |
resultCounts |
تم توسيع معلومات عدد النتائج. |
حقل الاتحاد
في حالة نادرة عندما يتعذر على النظام البحث في جميع المستندات، أعد تشغيل الاستعلام. يمكن أن تكون السمة " |
|
resultCountEstimate |
العدد المقدَّر للنتائج لطلب البحث هذا. |
resultCountExact |
عدد النتائج الدقيق لطلب البحث هذا. |
نطاقات الأذونات
يتطلب استخدام أحد نطاقات OAuth التالية:
https://www.googleapis.com/auth/cloud_search.query
https://www.googleapis.com/auth/cloud_search
لمزيد من المعلومات، راجِع دليل التفويض.
QueryInterpretationOptions
لتفسير طلب بحث المستخدم.
تمثيل JSON |
---|
{ "disableNlInterpretation": boolean, "enableVerbatimMode": boolean, "disableSupplementalResults": boolean } |
الحقول | |
---|---|
disableNlInterpretation |
علامة لإيقاف تفسير طلبات البحث باستخدام اللغة الطبيعية الإعداد التلقائي هو "خطأ"، ويمكنك ضبطه على "صحيح" لإيقاف ترجمة اللغة الطبيعية. لا ينطبق تفسير NL إلا على مصادر البيانات المحددة مسبقًا. |
enableVerbatimMode |
يمكنك تفعيل هذه العلامة لإيقاف جميع عمليات التحسين الداخلية، مثل ترجمة طلبات البحث باللغة الطبيعية واسترداد النتائج التكميلية واستخدام المرادفات، بما في ذلك الكلمات الرئيسية المخصّصة. سيتم إيقاف ترجمة Nl في حال صحة إحدى العلامتين. |
disableSupplementalResults |
يمكنك استخدام هذه العلامة لإيقاف النتائج التكميلية لطلب بحث. وسيكون لإعداد النتائج التكميلية الذي يتم اختياره على مستوى SearchApplication الأولوية في حال ضبطه على "صحيح". |
QueryInterpretation
تمثيل JSON |
---|
{ "interpretedQuery": string, "interpretationType": enum ( |
الحقول | |
---|---|
interpretedQuery |
تفسير طلب البحث المستخدم في البحث. على سبيل المثال، سيتم تفسير طلبات البحث ذات الغرض من اللغة الطبيعية، مثل "رسالة إلكترونية من هاني" على أنها "من:جون ص:البريد". لن يتم ملء هذا الحقل عندما يكون السبب NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY. |
interpretationType |
|
reason |
سبب تفسير طلب البحث. لن يتم اختيار هذا الحقل إذا كان نوع التفسير غير "بدون". |
QueryInterpretation.InterpretationType
عمليات التعداد | |
---|---|
NONE |
لا يتم استخدام تفسير اللغة الطبيعية أو النسخة الشاملة من طلب البحث لجلب نتائج البحث. |
BLEND |
يتم دمج النتائج من الاستعلام الأصلي مع النتائج الأخرى. يتم ملء حقل "السبب" أدناه بسبب مزج هذه النتائج الأخرى مع نتائج طلب البحث الأصلي. |
REPLACE |
يتم استبدال النتائج من طلب البحث الأصلي. يتم ملء حقل "السبب" أدناه بسبب استبدال النتائج من طلب البحث الأصلي. |
QueryInterpretation.Reason
عمليات التعداد | |
---|---|
UNSPECIFIED |
|
QUERY_HAS_NATURAL_LANGUAGE_INTENT |
يتم استخدام ترجمة طلب البحث باللغة الطبيعية لاسترجاع نتائج البحث. |
NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY |
يُستخدم تشابه عبارات البحث والوثائق لتوسيع طلب البحث بشكل انتقائي لاسترداد نتائج بحث إضافية نظرًا لعدم العثور على نتائج كافية لطلب بحث المستخدم. وسيكون طلب البحث المفسَّر فارغًا في هذه الحالة. |
SearchResult
النتائج التي تحتوي على معلومات مفهرَسة لمستند معيّن
تمثيل JSON |
---|
{ "title": string, "url": string, "snippet": { object ( |
الحقول | |
---|---|
title |
عنوان نتيجة البحث. |
url |
تمثّل هذه السمة عنوان URL لنتيجة البحث. يحتوي عنوان URL على إعادة توجيه Google إلى العنصر الفعلي. تمّ توقيع عنوان URL هذا ويجب عدم تغييره. |
snippet |
تمثّل هذه السمة تسلسل جميع المقتطفات (الملخصات) المتاحة لهذه النتيجة. |
metadata |
بيانات التعريف لنتيجة البحث. |
clusteredResults[] |
إذا كان المصدر مجمّعًا، قدِّم قائمة بالنتائج المجمّعة. سيكون هناك مستوى واحد فقط من النتائج المجمّعة. إذا لم يكن المصدر الحالي مفعَّلاً للتجميع العنقودي، سيكون هذا الحقل فارغًا. |
debugInfo |
تصحيح الأخطاء في المعلومات المتعلقة بنتيجة البحث هذه. |
المقتطف
مقتطف من نتيجة البحث يلخّص محتوى الصفحة الناتجة.
تمثيل JSON |
---|
{
"snippet": string,
"matchRanges": [
{
object ( |
الحقول | |
---|---|
snippet |
مقتطف المستند. مقتطف المستند. قد يحتوي على حرف HTML تم تخطّيه ويجب إلغاء تخطّيه قبل العرض. |
matchRanges[] |
النطاقات المطابقة في المقتطف. |
MatchRange
النطاق المطابق للمقتطف [البداية، النهاية).
تمثيل JSON |
---|
{ "start": integer, "end": integer } |
الحقول | |
---|---|
start |
تمثّل هذه السمة موضع بداية المطابقة في المقتطف. |
end |
نهاية المطابقة في المقتطف. |
البيانات الوصفية
البيانات الوصفية لنتيجة بحث مطابقة.
تمثيل JSON |
---|
{ "source": { object ( |
الحقول | |
---|---|
source |
المصدر المسمى للنتيجة، مثل Gmail. |
mimeType |
نوع MIME لنتيجة البحث. |
thumbnailUrl |
تمثّل هذه السمة عنوان URL للصورة المصغّرة للنتيجة. |
owner |
مالك المستند أو الكائن في نتيجة البحث (عادةً ما يكون منشئ المحتوى). |
createTime |
وقت الإنشاء لهذا المستند أو العنصر في نتيجة البحث. طابع زمني بتنسيق RFC3339 UTC "Zulu" ، بدقة نانو ثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
updateTime |
تاريخ آخر تعديل للعنصر في نتيجة البحث. إذا لم يتم ضبط السياسة في العنصر، تكون القيمة المعروضة هنا فارغة. عند استخدام طابع زمني بتنسيق RFC3339 UTC "Zulu" ، بدقة نانو ثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
fields[] |
الحقول المفهرَسة في البيانات المنظَّمة، يتم عرضها كسمة عامة باسم. |
displayOptions |
التي تحدّد كيفية عرض نتيجة بحث للبيانات المنظَّمة. |
objectType |
نوع الكائن لنتيجة البحث. |
ResultDisplayMetadata
تمثيل JSON |
---|
{
"objectTypeLabel": string,
"metalines": [
{
object ( |
الحقول | |
---|---|
objectTypeLabel |
تصنيف العرض للكائن. |
metalines[] |
محتوى الأسطر الوصفية الذي سيتم عرضه مع النتيجة. |
ResultDisplayMetadata.ResultDisplayLine
مجموعة الحقول التي يشكل سطرًا معروضًا
تمثيل JSON |
---|
{
"fields": [
{
object ( |
الحقول | |
---|---|
fields[] |
ResultDisplayMetadata.ResultDisplayField
حقول عرض لنتائج query.search
تمثيل JSON |
---|
{
"label": string,
"operatorName": string,
"property": {
object ( |
الحقول | |
---|---|
label |
تصنيف العرض للموقع. |
operatorName |
اسم عامل التشغيل للموقع. |
property |
زوج قيمة الاسم للسمة. |
ResultDebugInfo
تصحيح الأخطاء في معلومات النتيجة.
تمثيل JSON |
---|
{ "formattedDebugInfo": string } |
الحقول | |
---|---|
formattedDebugInfo |
معلومات تصحيح الأخطاء العامة التي تم تنسيقها للعرض |
StructuredResult
هي نتائج منظَّمة يتم عرضها كجزء من طلب البحث.
تمثيل JSON |
---|
{
"person": {
object ( |
الحقول | |
---|---|
person |
تمثيل شخص |
SpellResult
تمثيل JSON |
---|
{ "suggestedQuery": string } |
الحقول | |
---|---|
suggestedQuery |
الهجاء المقترح لطلب البحث. |
FacetResult
استجابة واجهة محددة للمصدر
تمثيل JSON |
---|
{
"sourceName": string,
"objectType": string,
"operatorName": string,
"buckets": [
{
object ( |
الحقول | |
---|---|
sourceName |
اسم المصدر الذي يتم عرض نتائج الواجهة له. لن يكون فارغًا. |
objectType |
نوع الكائن الذي يتم عرض نتائج الواجهة له. يمكن أن يكون الحقل فارغًا. |
operatorName |
اسم العامل الذي تم اختياره للواجهة. @see cloudsearch.SchemaPropertyOptions |
buckets[] |
facetBucket للقيم في الاستجابة التي تحتوي على نتيجة واحدة على الأقل مع الفلتر المقابل. |
FacetBucket
المجموعة في الواجهة هي وحدة التشغيل الأساسية. يمكن أن تتألف الحزمة من قيمة واحدة أو نطاق قيم متجاورة، بناءً على نوع الحقل الذي تمت إضافته إلى مجموعة البيانات. لا يتم استخدام FacetBucket حاليًا إلا لعرض كائن الاستجابة.
تمثيل JSON |
---|
{ "count": integer, "percentage": integer, "filter": { object ( |
الحقول | |
---|---|
count |
عدد النتائج التي تطابق قيمة الحزمة. لا يتم عرض الأعداد إلا لعمليات البحث عند ضمان دقة العدد. لا تضمن Cloud Search ظهور أعداد الواجهات لأي طلبات بحث، وقد لا تظهر أعداد الواجهات إلا بشكل متقطّع، حتى بالنسبة إلى طلبات البحث المتطابقة. لا تنشئ تبعيات على وجود عدد الواجهات، وبدلاً من ذلك استخدم النسب المئوية للواجهة التي يتم عرضها دائمًا. |
percentage |
النسبة المئوية للنتائج التي تطابق قيمة الحزمة. تتراوح القيمة المعروضة بين (0-100]، ويتم تقريبها إلى عدد صحيح إذا كانت كسرية. إذا لم يتم عرض القيمة بشكل صريح، فإنها تمثل قيمة مئوية يتم تقريبها إلى 0. يتم عرض النسب المئوية لجميع عمليات البحث، إلا أنها تقديرية. يجب عرض النسب المئوية بدلاً من الأعداد، لأن النسب المئوية يتم عرضها دائمًا. |
filter |
الفلتر الذي يتم تمريره في طلب البحث في حال اختيار مجموعة البيانات المناسبة. |
value |
|
ResponseDebugInfo
تصحيح الأخطاء في معلومات الرد.
تمثيل JSON |
---|
{ "formattedDebugInfo": string } |
الحقول | |
---|---|
formattedDebugInfo |
معلومات تصحيح الأخطاء العامة التي تم تنسيقها للعرض |
ErrorInfo
معلومات خطأ حول الردّ
تمثيل JSON |
---|
{
"errorMessages": [
{
object ( |
الحقول | |
---|---|
errorMessages[] |
|
ErrorMessage
رسالة خطأ لكل ردّ من المصدر.
تمثيل JSON |
---|
{
"source": {
object ( |
الحقول | |
---|---|
source |
|
errorMessage |
|
ResultCounts
معلومات عدد النتائج
تمثيل JSON |
---|
{
"sourceResultCounts": [
{
object ( |
الحقول | |
---|---|
sourceResultCounts[] |
معلومات حول عدد النتائج لكل مصدر يتضمن نتائج |
SourceResultCount
معلومات عدد النتائج حسب المصدر
تمثيل JSON |
---|
{ "source": { object ( |
الحقول | |
---|---|
source |
المصدر الذي ترتبط به معلومات عدد النتائج. |
hasMoreResults |
تحدّد هذه السمة ما إذا كان هناك المزيد من نتائج البحث عن هذا المصدر. |
حقل الاتحاد يمكن أن تكون السمة " |
|
resultCountEstimate |
العدد المقدَّر من النتائج لهذا المصدر |
resultCountExact |
تعرض هذه البيانات عدد النتائج الدقيق لهذا المصدر. |