สร้างอินเทอร์เฟซการค้นหาด้วย Query API

Query API มีวิธีการค้นหาและแนะนำสำหรับการสร้างอินเทอร์เฟซการค้นหาหรือฝังผลการค้นหาในแอปพลิเคชัน

สำหรับเว็บแอปพลิเคชันที่มีข้อกำหนดขั้นต่ำ ให้พิจารณาใช้วิดเจ็ตการค้นหา ดูข้อมูลเพิ่มเติมได้ที่หัวข้อสร้างอินเทอร์เฟซการค้นหาด้วยวิดเจ็ตการค้นหา

สร้างอินเทอร์เฟซการค้นหา

การสร้างอินเทอร์เฟซการค้นหาแบบมินิมอลต้องดำเนินการหลายขั้นตอน ดังนี้

1. กำหนดค่าแอปพลิเคชันการค้นหา
2. สร้างข้อมูลเข้าสู่ระบบ OAuth สําหรับแอปพลิเคชัน
3. ค้นหาดัชนี
4. แสดงผลการค้นหา

คุณสามารถปรับปรุงอินเทอร์เฟซการค้นหาเพิ่มเติมได้ด้วยฟีเจอร์ต่างๆ เช่น การแบ่งหน้า การเรียงลําดับ การกรอง แง่มุม และการแนะนำอัตโนมัติ

กำหนดค่าแอปพลิเคชันการค้นหา

คุณต้องสร้างแอปพลิเคชันการค้นหาอย่างน้อย 1 รายการเพื่อเชื่อมโยงกับอินเทอร์เฟซการค้นหาแต่ละรายการที่คุณสร้าง แอปพลิเคชันการค้นหามีพารามิเตอร์เริ่มต้นสําหรับการค้นหา เช่น แหล่งข้อมูลที่จะใช้ ลําดับการจัดเรียง ตัวกรอง และข้อมูลประกอบที่ต้องการขอ คุณลบล้างพารามิเตอร์เหล่านี้ได้หากจำเป็นโดยใช้ Query API

ดูข้อมูลเพิ่มเติมเกี่ยวกับแอปพลิเคชันการค้นหาได้ที่หัวข้อปรับแต่งประสบการณ์การค้นหาใน Cloud Search

สร้างข้อมูลเข้าสู่ระบบ OAuth สําหรับแอปพลิเคชัน

นอกเหนือจากขั้นตอนในกําหนดค่าการเข้าถึง Google Cloud Search API แล้ว คุณยังต้องสร้างข้อมูลเข้าสู่ระบบ OAuth สําหรับเว็บแอปพลิเคชันด้วย ประเภทของข้อมูลเข้าสู่ระบบที่คุณสร้างจะขึ้นอยู่กับบริบทที่ใช้ API

ใช้ข้อมูลเข้าสู่ระบบเพื่อขอสิทธิ์ในนามของผู้ใช้ ใช้ขอบเขต https://www.googleapis.com/auth/cloud_search.query เมื่อขอการให้สิทธิ์

ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือก OAuth และไลบรารีไคลเอ็นต์ได้ที่ [แพลตฟอร์มข้อมูลประจำตัวของ Google](https://developers.google.com/identity/choose-auth{: .external target="_blank"}

ค้นหาดัชนี

ใช้เมธอด search เพื่อค้นหาดัชนี

คำขอทุกรายการต้องมีข้อมูล 2 รายการ ได้แก่ ข้อความ queryเพื่อจับคู่รายการ และ searchApplicationId ที่ระบุรหัสสำหรับแอปพลิเคชันการค้นหาที่จะใช้

ข้อมูลโค้ดต่อไปนี้แสดงการค้นหาแหล่งข้อมูลภาพยนตร์สำหรับภาพยนตร์เรื่อง "ไททานิก"

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

แสดงผลการค้นหา

อย่างน้อยที่สุด อินเทอร์เฟซการค้นหาควรแสดงรายการ title รวมถึงลิงก์ไปยังรายการต้นฉบับ คุณเพิ่มประสิทธิภาพการแสดงผลการค้นหาได้โดยใช้ข้อมูลเพิ่มเติมที่มีอยู่ในผลการค้นหา เช่น ข้อมูลโค้ดที่ติดทั่วเว็บไซต์และข้อมูลเมตา

จัดการผลการค้นหาเพิ่มเติม

โดยค่าเริ่มต้น Cloud Search จะแสดงผลการค้นหาเพิ่มเติมเมื่อมีผลการค้นหาไม่เพียงพอสำหรับคำค้นหาของผู้ใช้ ช่อง queryInterpretation ในคำตอบจะระบุเวลาที่ระบบแสดงผลลัพธ์เสริม หากระบบแสดงเฉพาะผลการค้นหาเพิ่มเติม ระบบจะตั้งค่า InterpretationType เป็น REPLACE หากระบบแสดงผลลัพธ์ 2-3 รายการสําหรับคําค้นหาเดิมพร้อมกับผลการค้นหาเพิ่มเติม ระบบจะตั้งค่า InterpretationType เป็น BLEND ไม่ว่าในกรณีใด QueryInterpretation.Reason = NOT_ENOUGH_RESULTS_FOUND_FOR_USER_QUERY

เมื่อระบบแสดงผลลัพธ์เสริมบางส่วน ให้พิจารณาใส่ข้อความเพื่อระบุว่าระบบแสดงผลลัพธ์เสริม ตัวอย่างเช่น ในกรณีของ REPLACE คุณอาจแสดงสตริง "การค้นหาข้อความค้นหาเดิมของคุณไม่ตรงกับผลการค้นหาใดๆ กำลังแสดงผลการค้นหาสำหรับคำค้นหาที่คล้ายกัน"

ในกรณี BLEND คุณอาจแสดงสตริง "การค้นหาข้อความค้นหาเดิมของคุณไม่ตรงกับผลการค้นหามากพอ รวมผลการค้นหาสำหรับคำค้นหาที่คล้ายกัน"

จัดการผลการค้นหาบุคคล

Cloud Search จะแสดง "ผลการค้นหาบุคคล" 2 ประเภท ได้แก่ เอกสารที่เกี่ยวข้องกับบุคคลที่มีชื่อใช้อยู่ในคำค้นหา และข้อมูลพนักงานของบุคคลที่มีชื่อใช้อยู่ในคำค้นหา ผลการค้นหาประเภทหลังเป็นฟังก์ชันของฟีเจอร์การค้นหาบุคคลใน Cloud Search และผลการค้นหาสำหรับคำค้นหาดังกล่าวจะอยู่ในช่อง structuredResults ของการตอบกลับ Query API

{
  "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 ที่จัดทำดัชนีไว้ ระบบจะแสดงตัวอย่างเนื้อหา เนื้อหานี้ช่วยให้ผู้ใช้พิจารณาความเกี่ยวข้องของสินค้าที่ส่งคืนได้

หากมีข้อความค้นหาในสnippet ระบบจะแสดงผลช่วงการจับคู่อย่างน้อย 1 รายการที่ระบุตําแหน่งข้อความดังกล่าวด้วย

ใช้ matchRanges เพื่อไฮไลต์ข้อความที่ตรงกันเมื่อแสดงผลลัพธ์ ตัวอย่าง JavaScript ต่อไปนี้จะแปลงข้อมูลโค้ดเป็นมาร์กอัป 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 ของสินค้า รวมถึง Structured Data แบบส่งคืนได้ซึ่งเชื่อมโยงกับสินค้า

หากต้องการแสดง Structured Data ให้ใช้ช่อง displayOptions ฟิลด์ displayOptions มีป้ายกำกับที่แสดงสำหรับประเภทออบเจ็กต์ และชุด metalines เมตาบรรทัดแต่ละรายการคืออาร์เรย์ของคู่ป้ายกำกับที่แสดงและค่าตามที่กําหนดค่าไว้ในสคีมา

ดึงข้อมูลผลลัพธ์เพิ่มเติม

หากต้องการเรียกข้อมูลผลลัพธ์เพิ่มเติม ให้ตั้งค่าช่อง start ในคำขอเป็นออฟเซตที่ต้องการ คุณปรับขนาดของหน้าแต่ละหน้าได้โดยใช้ช่อง pageSize

หากต้องการแสดงจํานวนรายการที่แสดงหรือแสดงตัวควบคุมการแบ่งหน้าเพื่อเลื่อนดูรายการที่แสดง ให้ใช้ช่อง resultCount ระบบจะแสดงค่าจริงหรือค่าโดยประมาณ ทั้งนี้ขึ้นอยู่กับขนาดของชุดผลลัพธ์

จัดเรียงผลลัพธ์

ใช้ช่อง sortOptions เพื่อระบุลำดับของสินค้าที่ส่งคืน ค่า sortOptions เป็นออบเจ็กต์ที่มี 2 ช่อง ได้แก่

• operatorName — โอเปอเรเตอร์สำหรับพร็อพเพอร์ตี้ Structured Data เพื่อจัดเรียง สําหรับพร็อพเพอร์ตี้ที่มีโอเปอเรเตอร์หลายรายการ คุณจะจัดเรียงได้โดยใช้โอเปอเรเตอร์หลักที่เป็น "เท่ากับ" เท่านั้น
• sortOrder — ลำดับการจัดเรียง ซึ่งอาจเป็น ASCENDING หรือ DESCENDING

ระบบจะใช้ความเกี่ยวข้องเป็นคีย์การจัดเรียงรองด้วย หากไม่ได้ระบุลําดับการจัดเรียงในคําค้นหา ระบบจะจัดอันดับผลลัพธ์ตามความเกี่ยวข้องเท่านั้น

"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. ผู้ใช้เลือกค่าข้อมูลประกอบอย่างน้อย 1 ค่าเพื่อปรับแต่งผลลัพธ์
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 ค่าที่พบบ่อยที่สุดจะปรากฏก่อน

เมื่อผู้ใช้เลือกค่าอย่างน้อย 1 ค่าที่จะกรอง ให้สร้างการค้นหาใหม่ด้วยตัวกรองที่เลือกและค้นหา API อีกครั้ง

เพิ่มคำแนะนำ

ใช้ suggest API เพื่อแสดงการเติมข้อความอัตโนมัติสำหรับคำค้นหาโดยอิงตามประวัติการค้นหาส่วนตัวของผู้ใช้ รวมถึงรายชื่อติดต่อและชุดเอกสาร

ตัวอย่างเช่น การเรียกใช้ต่อไปนี้จะแสดงคําแนะนําสําหรับวลีบางส่วน jo

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

จากนั้นคุณก็แสดงคําแนะนําที่ได้ตามความเหมาะสมสําหรับแอปพลิเคชัน