Triển khai trình kết nối Microsoft SharePoint Online

Bạn có thể thiết lập Google Cloud Search để trả về kết quả từ nội dung trên SharePoint Online của tổ chức, ngoài nội dung trên Google Workspace. Bạn sử dụng trình kết nối Google Cloud Search SharePoint Online và định cấu hình trình kết nối đó để truy cập vào một nguồn dữ liệu SharePoint Online cụ thể.

Điểm quan trọng cần lưu ý

Chế độ cài đặt SharePoint được tôn trọng

Trình kết nối Cloud Search SharePoint Online luôn tuân theo chế độ cài đặt Chế độ hiển thị tìm kiếm trên SharePoint và bạn không thể ghi đè chế độ cài đặt này. Đối với tài liệu nháp, các quyền trên tài khoản người dùng (mà trình kết nối sử dụng để truy cập vào SharePoint Online) sẽ kiểm soát những tài liệu nháp được lập chỉ mục và trả về. Nếu tài khoản chỉ có quyền "Đọc toàn quyền", thì trình kết nối sẽ tuân theo chế độ cài đặt "Chế độ hiển thị mục nháp" trên SharePoint.

Bạn cũng có thể định cấu hình trình kết nối để giới hạn kết quả dựa trên quyền truy cập vào tài khoản người dùng. Để áp dụng tính năng cắt bớt nội dung bảo mật cho nội dung SharePoint, bạn đồng bộ hoá các danh tính bên ngoài sau đây với Google Directory:

  • Người dùng Office 365 / Azure AD
  • Nhóm bảo mật Office 365 / Azure AD
  • Nhóm SharePoint (có người dùng và nhóm Office 365 làm thành viên)

Tối ưu hoá cho công cụ tìm kiếm

Bạn có thể cải thiện trải nghiệm của người dùng bằng cách định cấu hình trình kết nối để trả về kết quả tìm kiếm phù hợp hơn.

Để sử dụng API, hãy đặt giá trị cho các tham số tạo HTML trong tệp cấu hình của trình kết nối SharePoint Online. Các thông số này cho phép bạn đặt những trường có tác động cao hơn hoặc thấp hơn đối với các kết quả trùng khớp.

Để thiết lập giản đồ, hãy làm theo hướng dẫn trong bài viết Tạo và đăng ký giản đồ. Khi bạn thiết lập giản đồ:

  • Để liên kết tên của các loại nội dung SharePoint với định nghĩa đối tượng tương ứng, trình kết nối sẽ chuẩn hoá tên loại nội dung bằng cách loại trừ các ký tự không được hỗ trợ. Đối với định nghĩa đối tượng, API Tìm kiếm trên đám mây chỉ hỗ trợ các ký tự hợp lệ là A-Z, a-z và 0-9. Ví dụ: loại nội dung "Thông báo" liên kết với định nghĩa đối tượng "Thông báo". Loại nội dung "Bài viết tin tức" liên kết với "NewsArticle" (không có dấu cách).

  • Khi không thể so khớp định nghĩa đối tượng với định nghĩa đối tượng, trình kết nối sẽ sử dụng loại đối tượng dự phòng (itemMetadata.objectType). Tìm hiểu thêm về các thông số cấu hình siêu dữ liệu.

  • Trình kết nối liên kết tên thuộc tính SharePoint với định nghĩa thuộc tính.

  • Khi gặp tệp .msg của Microsoft Outlook trong quá trình lập chỉ mục nội dung, trình kết nối sẽ ghi đè loại nội dung cho các tệp đó và lập chỉ mục dưới dạng application/vnd.ms-outlook.

Các hạn chế đã biết về trình kết nối

  • Mỗi thực thể của trình kết nối chỉ có thể lập chỉ mục nội dung từ một bộ sưu tập trang web. Để lập chỉ mục nhiều bộ sưu tập trang web, hãy thiết lập các thực thể trình kết nối bổ sung.
  • Mức sử dụng bộ nhớ tăng lên theo số lượng người dùng và nhóm riêng biệt mà bạn sử dụng trong ACL cho mỗi bộ sưu tập trang web.
  • Thông báo xoá không được gửi ngay lập tức và có thể mất hơn 4 giờ để trình kết nối nhận ra rằng người dùng đã xoá nội dung khỏi kho lưu trữ nguồn.

Yêu cầu hệ thống

Yêu cầu hệ thống
Hệ điều hành
  • Windows Server 2016
  • Ubuntu
  • Red Hat Enterprise Linux 5.0
  • SUSE Enterprise Linux 10 (64 bit)
Xác thực
  • Xác thực trực tiếp
Phần mềm
  • Môi trường SharePoint Online
  • Java JRE 1.8 đã cài đặt trên máy tính sẽ chạy trình kết nối Google Cloud Search SharePoint Online

Triển khai trình kết nối

Điều kiện tiên quyết

  1. Tạo khoá riêng tư Google Workspace chứa mã tài khoản dịch vụ của bạn. Để tìm hiểu cách lấy khoá riêng tư, hãy xem bài viết Thiết lập quyền truy cập vào API Google Cloud Search.

  2. Quản trị viên Google Workspace phải thêm nguồn dữ liệu để tìm kiếm. Ghi lại mã nguồn dữ liệu.

  3. Nếu trình kết nối trả về kết quả dựa trên ACL (kết quả không công khai), thì quản trị viên Google Workspace phải tạo hai nguồn danh tính và cung cấp cho bạn mã nhận dạng của các nguồn đó:

    • một nhóm cho người dùng và nhóm Office 365
    • một nhóm cho các nhóm SharePoint

    Quản trị viên cũng phải lấy mã khách hàng Google Workspace của tổ chức và cung cấp cho bạn.

    Tìm hiểu cách lấy các giá trị này trong bài viết Ánh xạ danh tính người dùng trong Cloud Search.

  4. Thiết lập tài khoản người dùng cho trình kết nối có đặc quyền Quản trị viên bộ sưu tập trang web SharePoint Online.

  5. Nếu trình kết nối trả về kết quả dựa trên ACL (kết quả không công khai), hãy tạo thông tin xác thực để đọc người dùng và nhóm từ tài khoản Office 365 của bạn. Làm theo hướng dẫn của Microsoft để tạo ứng dụng Azure Active Directory. Khi bạn thiết lập ứng dụng:

    1. Đặt tên cho ứng dụng bằng một tên mô tả, chẳng hạn như "gcs-o365-identity-connector".
    2. Thêm quyền. Ứng dụng cần có "Group.Read.All" và "User.Read.All".
    3. Ghi lại những thông tin sau để sử dụng trong cấu hình trình kết nối:
      • ID ứng dụng
      • Người thuê
      • Mật khẩu ứng dụng khách

Bước 1. Cài đặt phần mềm trình kết nối SharePoint Online

  1. Sao chép kho lưu trữ trình kết nối trên GitHub.

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

  2. Hãy xem phiên bản của trình kết nối mà bạn muốn:

    $ git checkout tags/v1-0.0.3

  3. Tạo trình kết nối.

    $ mvn package

    Để bỏ qua các bài kiểm thử khi tạo trình kết nối, hãy chạy mvn package -DskipTests thay vì mvn package.

  4. Sao chép tệp zip của trình kết nối vào thư mục cài đặt cục bộ:

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

Bước 2. Tạo tệp cấu hình trình kết nối SharePoint Online

  1. Trong cùng thư mục với quá trình cài đặt trình kết nối, hãy tạo một tệp mới và đặt tên là sharepoint-online-connector.config. Nếu bạn dự định chạy nhiều phiên bản trình kết nối, hãy thêm thông tin chi tiết vào tên để phân biệt các phiên bản đó.

  2. Thêm các tham số dưới dạng cặp khoá/giá trị vào nội dung tệp, như trong ví dụ sau:

    ### SharePoint Online connector configuration ###

# Required parameters for data source access
api.sourceId=08ef8becd116faa4546b8ca2c84b2879
api.serviceAccountPrivateKeyFile=service_account.json

# Required parameters for SharePoint Online access
sharepoint.server=https://mydomain.onmicrosoft.com
sharepoint.siteCollectionOnly=true
sharepoint.username=admin@mydomain.onmicrosoft.com
sharepoint.password=pa$sw0rd
sharepoint.formsAuthenticationMode=LIVE
sharepoint.deploymentType=ONLINE

# SharePoint identity mapping parameters
api.identitySourceId=08ef8becd116faa475de26d9b291fed9
api.referenceIdentitySources=defaultIdentitySource
api.referenceIdentitySource.defaultIdentitySource.id=08ef8becd116faa5d3783f8c5a80e5aa

# Optional SharePoint List Item metadata parameters
contentTemplate.sharepointItem.title=Title
contentTemplate.sharepointItem.unmappedColumnsMode=APPEND

    Để biết nội dung mô tả chi tiết về từng tham số, hãy xem tài liệu tham khảo về tham số cấu hình.

  3. (Không bắt buộc) Định cấu hình thêm các thông số của trình kết nối nếu cần. Để biết thông tin chi tiết, hãy xem phần Các tham số của trình kết nối do Google cung cấp.

Bước 3. Thiết lập tính năng ghi nhật ký cho trình kết nối SharePoint Online

  1. Tạo một thư mục có tên logs (nhật ký) trong cùng thư mục chứa tệp nhị phân của trình kết nối.

  2. Tạo một tệp được mã hoá Latin-1 có tên logging.properties trong cùng thư mục và thêm nội dung sau:

    handlers = java.util.logging.ConsoleHandler,java.util.logging.FileHandler
# Default log level
.level = INFO
# uncomment line below to increase logging level for SharePoint APIsa
#com.google.enterprise.cloudsearch.sharepoint.level=FINE

# uncomment line below to increase logging level to enable API trace
#com.google.api.client.http.level = FINE
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.FileHandler.pattern=logs/connector-sharepoint.%g.log
java.util.logging.FileHandler.limit=10485760
java.util.logging.FileHandler.count=10
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

Bước 4. Định cấu hình trình kết nối danh tính SharePoint Online

Bạn phải thực hiện bước này để áp dụng ACL dựa trên danh tính SharePoint Online cho kết quả tìm kiếm. Nếu thiết lập trình kết nối bằng ACL công khai, bạn có thể bỏ qua bước này.

  1. Trong cùng thư mục với quá trình cài đặt trình kết nối SharePoint Online, hãy tạo một tệp mới và đặt tên là sharepoint-online-identity-connector.config.

  2. Thêm các tham số dưới dạng cặp khoá/giá trị vào nội dung tệp, như trong ví dụ sau:

    ### SharePoint Online identity connector configuration ###
# Required parameters for data source access
api.customerId=C05d3djk8
api.serviceAccountPrivateKeyFile=service_account.json

# Required parameters for SharePoint Online access
sharepoint.server=https://mydomain.onmicrosoft.com
sharepoint.siteCollectionOnly=true
sharepoint.username=admin@mydomain.onmicrosoft.com
sharepoint.password=pa$sw0rd
sharepoint.formsAuthenticationMode=LIVE
sharepoint.deploymentType=ONLINE

# SharePoint identity mapping parameters
api.identitySourceId=08ef8becd116faa475de26d9b291fed9
api.referenceIdentitySources=defaultIdentitySource
api.referenceIdentitySource.defaultIdentitySource.id=08ef8becd116faa5d3783f8c5a80e5aa

    Các giá trị này gần giống với trình kết nối SharePoint Online, ngoại trừ việc thay vì api.sourceId, tham số là api.customerId. Giá trị của api.customerId là mã khách hàng mà bạn nhận được từ quản trị viên Google Workspace.

Bước 5. Cài đặt trình kết nối Danh tính Office 365

Bạn phải thực hiện bước này để áp dụng ACL dựa trên danh tính SharePoint Online cho kết quả tìm kiếm. Nếu thiết lập trình kết nối bằng ACL công khai, bạn có thể bỏ qua bước này.

  1. Sao chép kho lưu trữ trình kết nối trên GitHub.

    $ git clone https://github.com/google-cloudsearch/office-365-connector.git
$ cd office-365-connector

  2. Hãy xem phiên bản của trình kết nối mà bạn muốn:

    $ git checkout tags/v1-0.0.3

  3. Tạo trình kết nối.

    $ mvn package

    Để bỏ qua các bài kiểm thử khi tạo trình kết nối, hãy chạy mvn package -DskipTests thay vì mvn package.

  4. Sao chép tệp zip của trình kết nối vào thư mục cài đặt cục bộ:

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

Bước 6. Định cấu hình trình kết nối Danh tính Office 365 và thiết lập tính năng ghi nhật ký

  1. Trong cùng thư mục với quá trình cài đặt trình kết nối danh tính, hãy tạo một tệp mới và đặt tên là o365-identity-connector.config.

  2. Thêm các tham số dưới dạng cặp khoá/giá trị vào nội dung tệp, như trong ví dụ sau. Lưu ý: Tất cả thông số đều bắt buộc.

    ### Office 365 Identity connector configuration ###
    
api.identitySourceId=12345abcde
api.customerId=abcde12345
o365.clientId=a63c6eb3-29e7-486
o365.tenant=185ef9ed-29e7-486
o365.clientSecret=raHJN15vRLBKs

    Để biết nội dung mô tả chi tiết về từng tham số, hãy xem tài liệu tham khảo về cấu hình của trình kết nối Danh tính Office 365.

  3. Tạo một thư mục có tên logs (nhật ký) trong cùng thư mục chứa tệp nhị phân của trình kết nối.

  4. Tạo một tệp ASCII hoặc UTF-8 có tên logging.properties trong cùng thư mục và thêm nội dung sau:

    handlers = java.util.logging.ConsoleHandler,java.util.logging.FileHandler
# Default log level
.level = INFO
# uncomment line below to increase logging level for Office 365 APIs
#com.google.enterprise.cloudsearch.o365.level=FINE

# uncomment line below to increase logging level to enable Google API traces
#com.google.api.client.http.level = FINE
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.FileHandler.pattern=logs/connector-o365.%g.log
java.util.logging.FileHandler.limit=10485760
java.util.logging.FileHandler.count=10
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter

Bước 7. Chạy trình kết nối SharePoint Online

Trong các bước sau, bạn sẽ liên kết các thực thể chính trong cả Office 365 và bộ sưu tập trang web SharePoint với các danh tính trong dịch vụ Cloud Identity. Quá trình đồng bộ hoá này được thực hiện bằng trình kết nối danh tính Office 365 và trình kết nối danh tính SharePoint Online.

Sau khi trình kết nối Office 365 đồng bộ hoá người dùng và nhóm, hãy chạy trình kết nối danh tính SharePoint Online để đồng bộ hoá các nhóm bộ sưu tập trang web SharePoint. Sau đó, bạn chạy trình kết nối SharePoint Online để lập chỉ mục và phân phát kết quả cho người dùng Cloud Search.

  1. Chạy trình kết nối danh tính Office 365:

    $ java -Djava.util.logging.config.file=logging.properties -jar google-cloudsearch-office-365-connector-v1-0.0.3.jar -Dconfig=o365-identity-connector.config

  2. Chạy trình kết nối danh tính SharePoint Online:

    $ java -Djava.util.logging.config.file=logging.properties -cp "google-cloudsearch-sharepoint-connector-v1-0.0.3.jar" com.google.enterprise.cloudsearch.sharepoint.SharePointIdentityConnector -Dconfig=sharepoint-online-identity-connector.config

  3. Chạy trình kết nối SharePoint Online:

    $ java -Djava.util.logging.config.file=logging.properties -jar google-cloudsearch-sharepoint-connector-v1-0.0.3.jar -Dconfig=sharepoint-online-connector.config

Tài liệu tham khảo về tham số cấu hình

Truy cập nguồn dữ liệu

Xem xét Thông số
Mã nguồn dữ liệu api.sourceId=1234567890abcdef

Bắt buộc. Mã nguồn dữ liệu Google Cloud Search do quản trị viên Google Workspace thiết lập.
Đường dẫn đến tệp khoá riêng tư của tài khoản dịch vụ api.serviceAccountPrivateKeyFile=PrivateKey.json

Bắt buộc. Đường dẫn đến tệp khoá tài khoản dịch vụ Google Cloud Search.

Quyền truy cập vào SharePoint Online

Xem xét Thông số
Tên miền đủ điều kiện cho Tập hợp trang web SharePoint sharepoint.server=http://yoursharepoint.example.com/

Bắt buộc. Nếu tên miền không đủ điều kiện, hãy đặt chế độ ghi đè DNS trên máy chủ của trình kết nối.
Chế độ chỉ có thể xem bộ sưu tập trang web sharepoint.siteCollectionOnly=true

Bắt buộc. Đối với SharePoint Online, hãy đặt giá trị true.
Tên người dùng SharePoint sharepoint.username=username

Bắt buộc. Tên người dùng của tài khoản dùng để truy cập vào SharePoint Online.
Mật khẩu SharePoint sharepoint.password=user_password

Bắt buộc. Mật khẩu của tài khoản dùng để truy cập vào SharePoint Online.
Chế độ xác thực sharepoint.formsAuthenticationMode=LIVE

Bắt buộc. Đối với SharePoint Online, giá trị này luôn là "LIVE" (TRỰC TIẾP).
Loại hình triển khai sharepoint.deploymentType=ONLINE

Bắt buộc. Đối với SharePoint Online, giá trị này luôn là "TRỰC TUYẾN".

Ánh xạ danh tính SharePoint

Xem xét Thông số
Mã nguồn nhận dạng api.identitySourceId=1234567890abcdef

Bắt buộc. Mã nguồn nhận dạng Cloud Search cho nguồn nhận dạng nhóm SharePoint.
Tham chiếu nguồn nhận dạng api.referenceIdentitySources=defaultIdentitySource

Bắt buộc. Đối với SharePoint Online, giá trị này luôn là "defaultIdentitySource".
Tham chiếu mã nguồn nhận dạng api.referenceIdentitySource.defaultIdentitySource.id=112233abcd

Bắt buộc. Mã nguồn nhận dạng Cloud Search cho nguồn nhận dạng Người dùng và Nhóm Office 365.

Tạo nội dung HTML

Xem xét Thông số
Trường tiêu đề mẫu HTML contentTemplate.sharePointItem.title=Title

Trường SharePoint để dùng làm tiêu đề mẫu HTML cho HTML được tạo.
Các trường chất lượng tìm kiếm cao của nội dung HTML contentTemplate.sharePointItem.quality.high=highField1[,highField2,...]

Danh sách các trường được phân tách bằng dấu phẩy để đưa vào HTML được tạo dưới dạng các trường chất lượng cao. Khi cụm từ tìm kiếm khớp với các trường này, kết quả sẽ được xếp hạng cao hơn.
Trường chất lượng tìm kiếm trung bình cho nội dung HTML contentTemplate.sharePointItem.quality.medium=mediumField1[,mediumField2,...]

Danh sách các trường được phân tách bằng dấu phẩy để đưa vào HTML được tạo dưới dạng các trường có chất lượng trung bình.
Các trường chất lượng tìm kiếm thấp của nội dung HTML contentTemplate.sharePointItem.quality.low=lowField1[,lowField2,...]

Danh sách các trường được phân tách bằng dấu phẩy để đưa vào HTML đã tạo dưới dạng các trường chất lượng thấp.
Cột chưa liên kết nội dung HTML contentTemplate.sharepointItem.unmappedColumnsMode=APPEND

Cách trình kết nối xử lý các cột chưa được liên kết. Giá trị là APPEND (mặc định) hoặc IGNORE.

  • APPEND (Thêm vào)—Trình kết nối tạo nội dung HTML với tất cả các trường, bao gồm cả những trường không được đặt mức chất lượng (cao, trung bình hoặc thấp).
  • IGNORE (BỎ QUA) – Trình kết nối tạo nội dung HTML chỉ có các trường được liên kết.

Cấu hình trình kết nối danh tính Office 365

Xem xét Thông số
Mã nguồn nhận dạng api.identitySourceId=1234567890abcdef

Bắt buộc. Mã nguồn nhận dạng Office 365. Giá trị này phải khớp với giá trị của `api.referenceIdentitySource.defaultIdentitySource.id` trong cấu hình của trình kết nối SharePoint Online.
Mã khách hàng của Google api.customerId=c1b1d1e1

Bắt buộc. Mã khách hàng Google Workspace của tổ chức.
Mã ứng dụng Office 365 o365.clientId=a63c6eb3-29e7-486

Bắt buộc. Mã ứng dụng từ quá trình thiết lập ứng dụng Office 365.

Người dùng Office 365 o365.tenant=185ef9ed-29e7-486

Bắt buộc. Người thuê cho tài khoản Office 365 của bạn (ứng dụng Azure Activity Directory)
Khoá bí mật của ứng dụng khách Office 365 o365.clientSecret=raHJN15vRLBKs

Bắt buộc. Thông tin xác thực bí mật từ phần Thiết lập ứng dụng Office 365