SharePoint API: search namespace enhancements

vgrem · vgrem · commit 5e4a8fbc9988 · 2022-11-23T23:40:27.000+02:00
diff --git a/examples/sharepoint/search/export_reports.py b/examples/sharepoint/search/export_reports.py
@@ -9,4 +9,3 @@
     result = setting.export_search_reports(tenant_id="af6a80a4-8b4b-4879-88af-42ff8a545211",
                                            report_type="ReportTopQueries").execute_query()
     print(result)
-
diff --git a/examples/sharepoint/search/search_documents.py b/examples/sharepoint/search/search_documents.py
@@ -1,30 +1,10 @@
-import json
-
-from office365.runtime.auth.user_credential import UserCredential
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.search.request import SearchRequest
-from office365.sharepoint.search.service import SearchService
-from tests import test_site_url, settings
-
-
-def extract_cell_value(cells, name):
-    """
-    Extract cell value
-    """
-    return next((c.get("Value") for c in cells.values() if c.get("Key") == name), None)
-
+from tests import test_site_url, test_user_credentials
 
-user_credentials = UserCredential(settings.get('user_credentials', 'username'),
-                                  settings.get('user_credentials', 'password'))
-ctx = ClientContext(test_site_url).with_credentials(user_credentials)
-search = SearchService(ctx)
+ctx = ClientContext(test_site_url).with_credentials(test_user_credentials)
 
-request = SearchRequest(query_text="IsDocument:1", select_properties=["Title", "Path"],
-                        trim_duplicates=False, row_limit=50)
-result = search.post_query(request).execute_query()
-relevant_results = result.value.PrimaryQueryResult.RelevantResults
-for i in relevant_results['Table']['Rows']:
-    cur_cells = relevant_results['Table']['Rows'][i]['Cells']
-    file_url = extract_cell_value(cur_cells, "Path")
+result = ctx.search.post_query(query_text="IsDocument:1").execute_query()
+results = result.value.PrimaryQueryResult.RelevantResults
+for row in results.Table.Rows:
+    file_url = row.Cells["Path"]
     print(file_url)
-    # print(json.dumps(cells, sort_keys=True, indent=4))
diff --git a/examples/sharepoint/search/search_simple.py b/examples/sharepoint/search/search_simple.py
@@ -1,12 +1,8 @@
-import json
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.search.service import SearchService
 from tests import test_site_url, test_user_credentials
 
 ctx = ClientContext(test_site_url).with_credentials(test_user_credentials)
-search = SearchService(ctx)
-result = search.query("IsDocument:1").execute_query()
-relevant_results = result.value.PrimaryQueryResult.RelevantResults
-for i in relevant_results['Table']['Rows']:
-    cells = relevant_results['Table']['Rows'][i]['Cells']
-    print(json.dumps(cells, sort_keys=True, indent=4))
+result = ctx.search.query("IsDocument:1").execute_query()
+results = result.value.PrimaryQueryResult.RelevantResults
+for row in results.Table.Rows:
+    print(row.Cells["Path"])
diff --git a/examples/sharepoint/search/search_sort_list.py b/examples/sharepoint/search/search_sort_list.py
@@ -1,18 +1,12 @@
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.search.query.sort import Sort
-from office365.sharepoint.search.request import SearchRequest
-from office365.sharepoint.search.service import SearchService
+from office365.sharepoint.search.query.sort.sort import Sort
 from tests import test_site_url, test_user_credentials
 
 ctx = ClientContext(test_site_url).with_credentials(test_user_credentials)
-search = SearchService(ctx)
-
-request = SearchRequest(query_text="IsDocument:1",
-                        sort_list=[Sort("LastModifiedTime", 1)],
-                        select_properties=["Path", "LastModifiedTime"],
-                        row_limit=20)
-result = search.post_query(request).execute_query()
-relevant_results = result.value.PrimaryQueryResult.RelevantResults
-for r in relevant_results.get('Table').get('Rows').items():
-    cells = r[1].get('Cells')
-    print(cells[1].get('Value'))
+result = ctx.search.post_query(query_text="IsDocument:1",
+                               sort_list=[Sort("LastModifiedTime", 1)],
+                               select_properties=["Path", "LastModifiedTime"],
+                               row_limit=20).execute_query()
+results = result.value.PrimaryQueryResult.RelevantResults
+for row in results.Table.Rows:
+    print(row.Cells["Path"], row.Cells["LastModifiedTime"])
diff --git a/office365/sharepoint/search/custom_result.py b/office365/sharepoint/search/custom_result.py
@@ -2,4 +2,25 @@
 
 
 class CustomResult(ClientValue):
-    pass
+    """
+    This contains a list of query results, all of which are of the type specified in TableType.
+    """
+
+    def __init__(self, group_template_id=None, item_template_id=None, result_title=None, properties=None):
+        """
+        :param str group_template_id: Specifies the identifier of the layout template that specifies how the results
+            returned will be arranged.
+        :param str item_template_id: Specifies the identifier of the layout template that specifies how the result
+            item will be displayed.
+        :param str result_title: Specifies the title associated with results for the transformed query by query rule
+            action. MUST NOT be more than 64 characters in length.
+        :param dict properties: Specifies a property bag of key value pairs.
+        """
+        self.GroupTemplateId = group_template_id
+        self.ItemTemplateId = item_template_id
+        self.Properties = properties
+        self.ResultTitle = result_title
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.Office.Server.Search.REST.CustomResult"
diff --git a/office365/sharepoint/search/query/auto_completion_match.py b/office365/sharepoint/search/query/auto_completion_match.py
@@ -0,0 +1,9 @@
+from office365.runtime.client_value import ClientValue
+
+
+class QueryAutoCompletionMatch(ClientValue):
+    """Represents one match in the Source for the Query"""
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.SharePoint.Client.Search.Query.QueryAutoCompletionMatch"
diff --git a/office365/sharepoint/search/query/property.py b/office365/sharepoint/search/query/property.py
@@ -0,0 +1,19 @@
+from office365.runtime.client_value import ClientValue
+from office365.sharepoint.search.query.property_value import QueryPropertyValue
+
+
+class QueryProperty(ClientValue):
+    """This object stores additional or custom properties for a search query. A QueryProperty is structured
+    as name-value pairs."""
+
+    def __init__(self, name=None, value=QueryPropertyValue()):
+        """
+        :param str name: This property stores the name part of the QueryProperty name-value pair.
+        :param QueryPropertyValue value: This property stores the value part of the QueryProperty name-value pair.
+        """
+        self.Name = name
+        self.Value = value
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.SharePoint.Client.Search.Query.QueryPropertyValue"
diff --git a/office365/sharepoint/search/query/property_value.py b/office365/sharepoint/search/query/property_value.py
@@ -0,0 +1,10 @@
+from office365.runtime.client_value import ClientValue
+
+
+class QueryPropertyValue(ClientValue):
+    """This object is used to store values of predefined types. The object MUST have a value set for only
+    one of the property."""
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.SharePoint.Client.Search.Query.QueryPropertyValue"
diff --git a/office365/sharepoint/search/query_result.py b/office365/sharepoint/search/query_result.py
@@ -1,5 +1,8 @@
 from office365.runtime.client_value import ClientValue
+from office365.runtime.client_value_collection import ClientValueCollection
+from office365.sharepoint.search.custom_result import CustomResult
 from office365.sharepoint.search.refinement_results import RefinementResults
+from office365.sharepoint.search.relevant_results import RelevantResults
 
 
 class QueryResult(ClientValue):
@@ -8,12 +11,22 @@ class QueryResult(ClientValue):
     as specified in [MS-QSSWS] section 3.1.4.1.3.6.
     """
 
-    def __init__(self, query_id=None):
+    def __init__(self, query_id=None, custom_results=None, relevant_results=RelevantResults(), query_rule_id=None):
         """
         :param str query_id: Specifies the identifier for the search query
+        :param list[CustomResults] custom_results: CustomResults is a list that contains zero or more CustomResult
+            instances. A CustomResult instance is a ResultTable with ResultType of any kind (except RefinementResults,
+            RelevantResults, and SpecialTermResults)
+        :param RelevantResults relevant_results: This contains a list of query results, all of which are of the
+            type specified in TableType.
+        :param str query_rule_id: Specifies the unique identifier of the query rule that produced the result set.
+            MUST be {00000000-0000-0000-0000-000000000000} if the result set is not associated to a query rule.
         """
         self.QueryId = query_id
+        self.QueryRuleId = query_rule_id
         self.RefinementResults = RefinementResults()
+        self.CustomResults = ClientValueCollection(CustomResult, custom_results)
+        self.RelevantResults = relevant_results
 
     @property
     def entity_type_name(self):
diff --git a/office365/sharepoint/search/relevant_results.py b/office365/sharepoint/search/relevant_results.py
@@ -3,6 +3,11 @@
 
 
 class RelevantResults(ClientValue):
+    """
+    The RelevantResults table contains the actual query results. It MUST only be present if the ResultTypes element
+    in the properties element of the Execute message contains ResultType.RelevantResults,
+    as specified in section 2.2.5.5
+    """
 
     def __init__(self):
         super(RelevantResults, self).__init__()
diff --git a/office365/sharepoint/search/reports/base.py b/office365/sharepoint/search/reports/base.py
@@ -5,3 +5,7 @@ class ReportBase(ClientValue):
 
     def __init__(self):
         self.FarmId = None
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.Office.Server.Search.REST.ReportBase"
diff --git a/office365/sharepoint/search/reports/top_queries.py b/office365/sharepoint/search/reports/top_queries.py
@@ -2,4 +2,7 @@
 
 
 class ReportTopQueries(ReportBase):
-    pass
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.Office.Server.Search.REST.ReportTopQueries"
diff --git a/office365/sharepoint/search/service.py b/office365/sharepoint/search/service.py
@@ -44,13 +44,13 @@ def export_manual_suggestions(self):
     def export_popular_tenant_queries(self, count):
         """This method is used to get a list of popular search queries executed on the tenant.
         """
-        result = ClientResult(self.context, ClientValueCollection(PopularTenantQuery))
+        return_type = ClientResult(self.context, ClientValueCollection(PopularTenantQuery))
         payload = {
             "count": count,
         }
-        qry = ServiceOperationQuery(self, "exportpopulartenantqueries", None, payload, None, result)
+        qry = ServiceOperationQuery(self, "exportpopulartenantqueries", None, payload, None, return_type)
         self.context.add_query(qry)
-        return result
+        return return_type
 
     def query(self, request_or_query):
         """The operation is used to retrieve search results by using the HTTP protocol with the GET method.
@@ -74,15 +74,23 @@ def _construct_request(request):
         self.context.before_execute(_construct_request)
         return result
 
-    def post_query(self, request):
+    def post_query(self, query_text, select_properties=None, trim_duplicates=None, row_limit=None, **kwargs):
         """The operation is used to retrieve search results through the use of the HTTP protocol
         with method type POST.
 
-        :type request: office365.sharepoint.search.request.SearchRequest"""
-        result = ClientResult(self.context, SearchResult())
-        qry = ServiceOperationQuery(self, "postquery", None, request, "request", result)
+        :param str query_text: The query text of the search query.
+        :param list[str] select_properties: Specifies a property bag of key value pairs.
+        :param bool trim_duplicates:  Specifies whether duplicates are removed by the protocol server before sorting,
+             selecting, and sending the search results.
+        :param int row_limit: The number of search results the protocol client wants to receive, starting at the index
+            specified in the StartRow element. The RowLimit value MUST be greater than or equal to zero.
+        """
+        return_type = ClientResult(self.context, SearchResult())
+        request = SearchRequest(query_text=query_text, select_properties=select_properties,
+                                trim_duplicates=trim_duplicates, row_limit=row_limit, **kwargs)
+        qry = ServiceOperationQuery(self, "postquery", None, request, "request", return_type)
         self.context.add_query(qry)
-        return result
+        return return_type
 
     def record_page_click(self):
         """The operation is used to record page clicks"""
@@ -91,10 +99,10 @@ def record_page_click(self):
     def search_center_url(self):
         """The operation is used to get the URI address of the search center by using the HTTP protocol
         with the GET method. The operation returns the URI of the of the search center."""
-        result = ClientResult(self.context)
-        qry = ServiceOperationQuery(self, "searchCenterUrl", None, None, None, result)
+        return_type = ClientResult(self.context)
+        qry = ServiceOperationQuery(self, "searchCenterUrl", None, None, None, return_type)
         self.context.add_query(qry)
-        return result
+        return return_type
 
     def results_page_address(self):
         """The operation is used to get the URI address of the result page by using the HTTP protocol
@@ -107,13 +115,13 @@ def suggest(self, query_text):
              is not specified, a default value of an empty string MUST be used, and the server MUST return a
              FaultException<ExceptionDetail> message.
         """
-        result = ClientResult(self.context, QuerySuggestionResults())
+        return_type = ClientResult(self.context, QuerySuggestionResults())
         payload = {
             "querytext": query_text
         }
-        qry = ServiceOperationQuery(self, "suggest", None, payload, None, result)
+        qry = ServiceOperationQuery(self, "suggest", None, payload, None, return_type)
         self.context.add_query(qry)
-        return result
+        return return_type
 
     def auto_completions(self, query_text, sources=None, number_of_completions=None, cursor_position=None):
         """
diff --git a/office365/sharepoint/search/simple_data_row.py b/office365/sharepoint/search/simple_data_row.py
@@ -0,0 +1,17 @@
+from office365.runtime.client_value import ClientValue
+
+
+class SimpleDataRow(ClientValue):
+
+    def __init__(self, cells=None):
+        if cells is None:
+            cells = {}
+        self.Cells = cells
+
+    def set_property(self, k, v, persist_changes=True):
+        for k, v in v.items():
+            key = v.get('Key', None)
+            type_name = v.get('ValueType', None)
+            if key is not None:
+                self.Cells[key] = v.get("Value")
+        return self
diff --git a/office365/sharepoint/search/simple_data_table.py b/office365/sharepoint/search/simple_data_table.py
@@ -1,5 +1,16 @@
 from office365.runtime.client_value import ClientValue
+from office365.runtime.client_value_collection import ClientValueCollection
+from office365.sharepoint.search.simple_data_row import SimpleDataRow
 
 
 class SimpleDataTable(ClientValue):
-    pass
+
+    def __init__(self, rows=None):
+        """
+        :param list[SimpleDataRow] rows:
+        """
+        self.Rows = ClientValueCollection(SimpleDataRow, rows)
+
+    @property
+    def entity_type_name(self):
+        return "SP.SimpleDataTable"
diff --git a/tests/sharepoint/test_search.py b/tests/sharepoint/test_search.py
@@ -34,8 +34,7 @@ def test3_get_search_center_url(self):
         self.assertIsNotNone(result.value)
 
     def test4_search_post_query(self):
-        request = SearchRequest("filename:guide.docx")
-        result = self.search.post_query(request).execute_query()
+        result = self.search.post_query(query_text="filename:guide.docx").execute_query()
         self.assertIsInstance(result.value, SearchResult)
         self.assertIsInstance(result.value.PrimaryQueryResult, QueryResult)
 
