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 AppSheet Trực tuyến của tổ chức cùng với nội dung trên Google Workspace. Bạn sử dụng trình kết nối Google Cloud Search POS Online và định cấu hình trình kết nối này để truy cập vào một nguồn dữ liệu SaaS trực tuyến cụ thể.

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

Cài đặt AppSheet danh dự

Trình kết nối Cloud Search sách trực tuyến luôn tuân thủ chế độ cài đặt Chế độ hiển thị tìm kiếm trên POS và bạn không thể ghi đè chế độ 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 POS Online) kiểm soát những tài liệu nháp nào được lập chỉ mục và trả về. Nếu tài khoản chỉ có quyền "Đọc đầy đủ", trình kết nối sẽ tuân theo cài đặt "Chế độ hiển thị mục nháp" trên AppSheet.

Bạn cũng đị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 tài khoản của người dùng. Để áp dụng tính năng cắt bỏ bảo mật cho nội dung trong Perfetto, bạn đồng bộ hoá các danh tính bên ngoài sau với Thư mục Google:

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

Tối ưu hoá chiến dịch Tìm kiếm

Bạn có thể cải thiện trải nghiệm 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 có liên quan hơn.

Để sử dụng API này, hãy đặt giá trị cho thông số tạo HTML trong tệp cấu hình trình kết nối AppSheet Trực tuyến. 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 đến kết quả 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 đồ:

  • Để ánh xạ tên của các loại nội dung Perfetto với các định nghĩa đối tượng tương ứng, trình kết nối 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 các định nghĩa về đối tượng, Cloud Search API chỉ hỗ trợ các ký tự hợp lệ từ 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 "Tin tức" sẽ liên kết thành "Tin bài" (không có dấu cách).

  • Khi trình kết nối không thể 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ề 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 POS với định nghĩa thuộc tính.

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

Hạn chế đã biết của trình kết nối

  • Mỗi phiên bản trình kết nối chỉ có thể lập chỉ mục nội dung từ một tập hợp trang web. Để lập chỉ mục nhiều tập hợp trang web, hãy thiết lập thêm bản sao trình kết nối.
  • Mức sử dụng bộ nhớ tăng theo số lượng người dùng và nhóm duy nhất mà bạn sử dụng trong các ACL cho mỗi tập hợp trang web.
  • Việc xoá thông báo sẽ không diễn ra 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 về hệ thống

Yêu cầu về 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 AppSheet Trực tuyến
  • Java JRE 1.8 được cài đặt trên máy tính sẽ chạy trình kết nối Google Cloud Search thương trực tuyến

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

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

  1. Tạo một khoá riêng tư trên Google Workspace, trong đó 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 chuyển đến bài viết Thiết lập quyền truy cập vào Google Cloud Search API.

  2. Quản trị viên Google Workspace của bạn phải thêm một 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 các ACL (kết quả không công khai), thì quản trị viên Google Workspace của bạn phải tạo 2 nguồn nhận dạng và cung cấp cho bạn mã nhận dạng của họ:

    • một quy tắc cho người dùng và nhóm Office 365
    • một mã cho nhóm Perfetto

    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 Bản đồ danh tính người dùng trên 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 của Quản trị viên thu thập trang web trực tuyến theo POS.

  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 đăng nhập để đọ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 mô tả cho ứng dụng, 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 thông tin sau để sử dụng trong cấu hình trình kết nối:
      • Mã ứng dụng
      • Đội chủ nhà
      • 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 AppSheet Trực tuyến

  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. Kiểm tra phiên bản trình kết nối mong muốn:

    $ git checkout tags/v1-0.0.3

  3. Xây dựng trình kết nối.

    $ mvn package

    Để bỏ qua các lượt 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 trên máy:

    $ 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 POS Online

  1. Trong cùng thư mục với thư mục cài đặt trình kết nối, hãy tạo một tệp mới rồi đặt tên tệp đó 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 nhiều thông tin chi tiết hơn vào tên để phân biệt.

  2. Thêm 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 thông số, hãy chuyển đến tài liệu tham khảo về thông số cấu hình.

  3. (Không bắt buộc) Định cấu hình các thông số trình kết nối bổ sung nếu cần. Để biết thông tin chi tiết, hãy xem bài viết Thông số 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 POS Online

  1. Tạo một thư mục có tên 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á theo kiểu 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 thông tin nhận dạng POS Online

Bước này là bắt buộc để áp dụng các ACL dựa trên danh tính của AppSheet trực tuyến cho kết quả tìm kiếm. Nếu bạn thiết lập trình kết nối bằng các 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 POS Online, hãy tạo một tệp mới rồi đặt tên tệp đó là sharepoint-online-identity-connector.config.

  2. Thêm 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 AppSheet Trực tuyến, ngoại trừ việc tham số này là api.customerId thay vì api.sourceId. 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 Identity Office 365

Bước này là bắt buộc để áp dụng các ACL dựa trên danh tính của AppSheet trực tuyến cho kết quả tìm kiếm. Nếu bạn thiết lập trình kết nối bằng các 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. Kiểm tra phiên bản trình kết nối mong muốn:

    $ git checkout tags/v1-0.0.3

  3. Xây dựng trình kết nối.

    $ mvn package

    Để bỏ qua các lượt 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 trên máy:

    $ 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 Identity 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 rồi đặt tên tệp đó là o365-identity-connector.config.

  2. Thêm 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ả cá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 chuyển đến tài liệu tham khảo về cấu hình của trình kết nối Office 365 Identity.

  3. Tạo một thư mục có tên 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. Khởi chạy trình kết nối Perfetto trực tuyến

Trong các bước sau, bạn sẽ ánh xạ các đối tượng chính trong cả Office 365 và tập hợp trang web Perfetto 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 Identity của Office 365 và trình kết nối thông tin nhận dạng SaaS.

Sau khi trình kết nối Office 365 đồng bộ hoá người dùng và nhóm, chạy trình kết nối thông tin nhận dạng AppSheet trực tuyến để đồng bộ hoá các nhóm tập hợp trang web dùng POS. Sau đó, bạn chạy trình kết nối AppSheet Trực tuyến để lập chỉ mục và cung cấp kết quả cho người dùng Cloud Search của mình.

  1. Chạy trình kết nối danh tính của 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 AppSheet Trực tuyến:

    $ 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 AppSheet Trực tuyến:

    $ 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ề thông 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 AppSheet Trực tuyến

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

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

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

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

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

Bắt buộc. Đối với POS Online, giá trị luôn là "LIVE".
Loại triển khai sharepoint.deploymentType=ONLINE

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

Liên kết danh tính Perfetto

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

Bắt buộc. Mã nguồn nhận dạng trên Cloud Search cho nguồn nhận dạng của nhóm SaaS.
Nguồn nhận dạng tệp đối chiếu api.referenceIdentitySources=defaultIdentitySource

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

Bắt buộc. Mã nguồn nhận dạng trên Cloud Search cho người dùng và nhóm của 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 POS để sử dụng làm tiêu đề mẫu HTML cho HTML đã tạo.
Trường chất lượng tìm kiếm cao cho 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 đã tạo dưới dạng trường chất lượng cao. Khi cụm từ truy vấn tìm kiếm khớp với những trường này, kết quả sẽ được xếp hạng cao hơn.
Trường nội dung HTML có chất lượng tìm kiếm trung bình 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 đã tạo dưới dạng các trường có chất lượng trung bình.
Các trường nội dung HTML có chất lượng tìm kiếm thấp 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 trường chất lượng thấp.
Cột nội dung HTML chưa được ánh xạ 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 TIP.

  • PHỤ LỤC—Trình kết nối tạo nội dung HTML có tất cả các trường, bao gồm cả những trường không được thiết lập mức chất lượng (cao, trung bình hoặc thấp).
  • 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 mã nhận dạng Office 365

Xem xét Thông số
ID 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 trình kết nối POS Online.
Id khách hàng Google api.customerId=c1b1d1e1

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

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

Người thuê văn phòng 365 o365.tenant=185ef9ed-29e7-486

Bắt buộc. Đối tượng thuê cho tài khoản Office 365 của bạn (ứng dụng Azure Activity Directory)
Mật khẩu ứng dụng khách Office 365 o365.clientSecret=raHJN15vRLBKs

Bắt buộc. Khoá bí mật về thông tin đăng nhập trong quá trình thiết lập Ứng dụng Office 365