/******************************************************************************* * Copyright 2012-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. * Licensed under the Apache License, Version 2.0 (the "License"). You may not use * this file except in compliance with the License. A copy of the License is located at * * http://aws.amazon.com/apache2.0 * * or in the "license" file accompanying this file. * This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR * CONDITIONS OF ANY KIND, either express or implied. See the License for the * specific language governing permissions and limitations under the License. * ***************************************************************************** * * AWS Tools for Windows (TM) PowerShell (TM) * */ using System; using System.Collections.Generic; using System.Management.Automation; using Amazon.PowerShell.Common; using Amazon.Runtime; using Amazon.CloudSearchDomain; using Amazon.CloudSearchDomain.Model; namespace Amazon.PowerShell.Cmdlets.CSD { /// /// Retrieves a list of documents that match the specified search criteria. How you specify /// the search criteria depends on which query parser you use. Amazon CloudSearch supports /// four query parsers: /// /// /// For more information, see Searching /// Your Data in the Amazon CloudSearch Developer Guide. /// /// The endpoint for submitting Search requests is domain-specific. You submit /// search requests to a domain's search endpoint. To get the search endpoint for your /// domain, use the Amazon CloudSearch configuration service DescribeDomains /// action. A domain's endpoints are also displayed on the domain dashboard in the Amazon /// CloudSearch console. /// /// /// Note: For scripts written against earlier versions of this module this cmdlet can also be invoked with the alias Search-CSDDocuments. /// /// [Cmdlet("Search", "CSDDocument")] [OutputType("Amazon.CloudSearchDomain.Model.SearchResponse")] [AWSCmdlet("Calls the Amazon CloudSearchDomain Search API operation.", Operation = new[] { "Search" }, SelectReturnType = typeof(Amazon.CloudSearchDomain.Model.SearchResponse), LegacyAlias = "Search-CSDDocuments")] [AWSCmdletOutput("Amazon.CloudSearchDomain.Model.SearchResponse", "This cmdlet returns an Amazon.CloudSearchDomain.Model.SearchResponse object containing multiple properties. The object can also be referenced from properties attached to the cmdlet entry in the $AWSHistory stack." )] public class SearchCSDDocumentCmdlet : AmazonCloudSearchDomainClientCmdlet, IExecutor { #region Parameter ServiceUrl /// /// Specifies the Search or Document service endpoint. /// [Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true, ValueFromPipelineByPropertyName = true)] [Amazon.PowerShell.Common.AWSRequiredParameter] public System.String ServiceUrl { get; set; } #endregion #region Parameter Cursor /// /// Retrieves a cursor value you can use to page through large result sets. Use /// the size parameter to control the number of hits to include in each response. /// You can specify either the cursor or start parameter /// in a request; they are mutually exclusive. To get the first cursor, set the cursor /// value to initial. In subsequent requests, specify the cursor value returned /// in the hits section of the response. /// /// For more information, see Paginating /// Results in the Amazon CloudSearch Developer Guide. /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.String Cursor { get; set; } #endregion #region Parameter Expr /// /// /// Defines one or more numeric expressions that can be used to sort results or specify /// search or filter criteria. You can also specify expressions as return fields. /// /// /// /// You specify the expressions in JSON using the form {"EXPRESSIONNAME":"EXPRESSION"}. /// You can define and use multiple expressions in a search request. For example: /// /// /// /// {"expression1":"_score*rating", "expression2":"(1/rank)*year"} /// /// /// /// For information about the variables, operators, and functions you can use in expressions, /// see Writing /// Expressions in the Amazon CloudSearch Developer Guide. /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.String Expr { get; set; } #endregion #region Parameter Facet /// /// /// Specifies one or more fields for which to get facet information, and options that /// control how the facet information is returned. Each specified field must be facet-enabled /// in the domain configuration. The fields and options are specified in JSON using the /// form {"FIELD":{"OPTION":VALUE,"OPTION:"STRING"},"FIELD":{"OPTION":VALUE,"OPTION":"STRING"}}. /// /// /// /// You can specify the following faceting options: /// /// /// /// If no facet options are specified, facet counts are computed for all field values, /// the facets are sorted by facet count, and the top 10 facets are returned in the results. /// /// /// /// To count particular buckets of values, use the buckets option. For example, /// the following request uses the buckets option to calculate and return /// facet counts by decade. /// /// /// /// {"year":{"buckets":["[1970,1979]","[1980,1989]","[1990,1999]","[2000,2009]","[2010,}"]}} /// /// /// /// /// To sort facets by facet count, use the count option. For example, the /// following request sets the sort option to count to sort /// the facet values by facet count, with the facet values that have the most matching /// documents listed first. Setting the size option to 3 returns only the /// top three facet values. /// /// /// /// {"year":{"sort":"count","size":3}} /// /// /// /// To sort the facets by value, use the bucket option. For example, the /// following request sets the sort option to bucket to sort /// the facet values numerically by year, with earliest year listed first. /// /// /// /// {"year":{"sort":"bucket"}} /// /// /// /// For more information, see Getting /// and Using Facet Information in the Amazon CloudSearch Developer Guide. /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.String Facet { get; set; } #endregion #region Parameter FilterQuery /// /// Specifies a structured query that filters the results of a search without affecting /// how the results are scored and sorted. You use filterQuery in conjunction /// with the query parameter to filter the documents that match the constraints /// specified in the query parameter. Specifying a filter controls only which /// matching documents are included in the results, it has no effect on how they are scored /// and sorted. The filterQuery parameter supports the full structured query /// syntax. /// /// For more information about using filters, see Filtering /// Matching Documents in the Amazon CloudSearch Developer Guide. /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.String FilterQuery { get; set; } #endregion #region Parameter Highlight /// /// /// Retrieves highlights for matches in the specified text or text-array /// fields. Each specified field must be highlight enabled in the domain configuration. /// The fields and options are specified in JSON using the form {"FIELD":{"OPTION":VALUE,"OPTION:"STRING"},"FIELD":{"OPTION":VALUE,"OPTION":"STRING"}}. /// /// /// /// You can specify the following highlight options: /// /// /// /// If no highlight options are specified for a field, the returned field text is treated /// as HTML and the first match is highlighted with emphasis tags: <em>search-term</em>. /// /// /// /// For example, the following request retrieves highlights for the actors /// and title fields. /// /// /// /// { "actors": {}, "title": {"format": "text","max_phrases": 2,"pre_tag": "","post_tag": /// ""} } /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.String Highlight { get; set; } #endregion #region Parameter Partial /// /// Enables partial results to be returned if one or more index partitions are unavailable. /// When your search index is partitioned across multiple search instances, by default /// Amazon CloudSearch only returns results if every partition can be queried. This means /// that the failure of a single search instance can result in 5xx (internal server) errors. /// When you enable partial results, Amazon CloudSearch returns whatever results are available /// and includes the percentage of documents searched in the search results (percent-searched). /// This enables you to more gracefully degrade your users' search experience. For example, /// rather than displaying no results, you could display the partial results and a message /// indicating that the results might be incomplete due to a temporary system outage. /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.Boolean? Partial { get; set; } #endregion #region Parameter Query /// /// Specifies the search criteria for the request. How you specify the search /// criteria depends on the query parser used for the request and the parser options /// specified in the queryOptions parameter. By default, the /// simple query parser is used to process requests. To use the structured, /// lucene, or dismax query parser, you must also specify /// the queryParser parameter. /// /// For more information about specifying search criteria, see Searching /// Your Data in the Amazon CloudSearch Developer Guide. /// /// [Parameter(Position = 1, ValueFromPipelineByPropertyName = true)] public System.String Query { get; set; } #endregion #region Parameter QueryOption /// /// /// Configures options for the query parser specified in the queryParser /// parameter. You specify the options in JSON using the following form {"OPTION1":"VALUE1","OPTION2":VALUE2"..."OPTIONN":"VALUEN"}. /// /// /// /// The options you can configure vary according to which parser you use: /// /// /// [Parameter(ValueFromPipelineByPropertyName = true)] [Alias("QueryOptions")] public System.String QueryOption { get; set; } #endregion #region Parameter QueryParser /// /// /// Specifies which query parser to use to process the request. If queryParser /// is not specified, Amazon CloudSearch uses the simple query parser. /// /// /// Amazon CloudSearch supports four query parsers: /// /// /// [Parameter(ValueFromPipelineByPropertyName = true)] [AWSConstantClassSource("Amazon.CloudSearchDomain.QueryParser")] public Amazon.CloudSearchDomain.QueryParser QueryParser { get; set; } #endregion #region Parameter Return /// /// Specifies the field and expression values to include in the response. Multiple fields /// or expressions are specified as a comma-separated list. By default, a search response /// includes all return enabled fields (_all_fields). To /// return only the document IDs for the matching documents, specify _no_fields. /// To retrieve the relevance score calculated for each document, specify /// _score. /// /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.String Return { get; set; } #endregion #region Parameter Size /// /// Specifies the maximum number of search hits to include in the response. /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.Int64? Size { get; set; } #endregion #region Parameter Sort /// /// Specifies the fields or custom expressions to use to sort the search results. /// Multiple fields or expressions are specified as a comma-separated list. You /// must specify the sort direction (asc or desc) for /// each field; for example, year desc,title asc. To use a field /// to sort results, the field must be sort-enabled in the domain configuration. /// Array type fields cannot be used for sorting. If no sort parameter /// is specified, results are sorted by their default relevance scores in descending /// order: _score desc. You can also sort by document ID /// (_id asc) and version (_version desc). /// /// For more information, see Sorting /// Results in the Amazon CloudSearch Developer Guide. /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.String Sort { get; set; } #endregion #region Parameter Start /// /// Specifies the offset of the first search hit you want to return. Note that the result /// set is zero-based; the first result is at index 0. You can specify either the start /// or cursor parameter in a request, they are mutually exclusive. /// /// For more information, see Paginating /// Results in the Amazon CloudSearch Developer Guide. /// /// [Parameter(ValueFromPipelineByPropertyName = true)] public System.Int64? Start { get; set; } #endregion #region Parameter UseAnonymousCredentials /// /// If set, the cmdlet calls the service operation using anonymous credentials. /// [Parameter(ValueFromPipelineByPropertyName = true)] public SwitchParameter UseAnonymousCredentials { get; set; } #endregion #region Parameter Select /// /// Use the -Select parameter to control the cmdlet output. The default value is '*'. /// Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.CloudSearchDomain.Model.SearchResponse). /// Specifying the name of a property of type Amazon.CloudSearchDomain.Model.SearchResponse will result in that property being returned. /// Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value. /// [System.Management.Automation.Parameter] public string Select { get; set; } = "*"; #endregion protected override void ProcessRecord() { this._ExecuteWithAnonymousCredentials = this.UseAnonymousCredentials.IsPresent; base.ProcessRecord(); var context = new CmdletContext(); if (ParameterWasBound(nameof(this.Select))) { context.Select = CreateSelectDelegate(Select) ?? throw new System.ArgumentException("Invalid value for -Select parameter.", nameof(this.Select)); } context.ServiceUrl = this.ServiceUrl; context.Cursor = this.Cursor; context.Expr = this.Expr; context.Facet = this.Facet; context.FilterQuery = this.FilterQuery; context.Highlight = this.Highlight; context.Partial = this.Partial; context.Query = this.Query; context.QueryOptions = this.QueryOption; context.QueryParser = this.QueryParser; context.Return = this.Return; context.Size = this.Size; context.Sort = this.Sort; context.Start = this.Start; var output = Execute(context) as CmdletOutput; ProcessOutput(output); } #region IExecutor Members public object Execute(ExecutorContext context) { var cmdletContext = context as CmdletContext; // create request var request = new SearchRequest(); if (cmdletContext.Cursor != null) { request.Cursor = cmdletContext.Cursor; } if (cmdletContext.Expr != null) { request.Expr = cmdletContext.Expr; } if (cmdletContext.Facet != null) { request.Facet = cmdletContext.Facet; } if (cmdletContext.FilterQuery != null) { request.FilterQuery = cmdletContext.FilterQuery; } if (cmdletContext.Highlight != null) { request.Highlight = cmdletContext.Highlight; } if (cmdletContext.Partial != null) { request.Partial = cmdletContext.Partial.Value; } if (cmdletContext.Query != null) { request.Query = cmdletContext.Query; } if (cmdletContext.QueryOptions != null) { request.QueryOptions = cmdletContext.QueryOptions; } if (cmdletContext.QueryParser != null) { request.QueryParser = cmdletContext.QueryParser; } if (cmdletContext.Return != null) { request.Return = cmdletContext.Return; } if (cmdletContext.Size != null) { request.Size = cmdletContext.Size.Value; } if (cmdletContext.Sort != null) { request.Sort = cmdletContext.Sort; } if (cmdletContext.Start != null) { request.Start = cmdletContext.Start.Value; } CmdletOutput output; // issue call using (var client = CreateClient(cmdletContext.ServiceUrl)) { try { var response = CallAWSServiceOperation(client, request); object pipelineOutput = cmdletContext.Select(response, this); output = new CmdletOutput { PipelineOutput = pipelineOutput, ServiceResponse = response }; } catch (Exception e) { output = new CmdletOutput { ErrorResponse = e }; } return output; } } public ExecutorContext CreateContext() { return new CmdletContext(); } #endregion #region AWS Service Operation Call private Amazon.CloudSearchDomain.Model.SearchResponse CallAWSServiceOperation(IAmazonCloudSearchDomain client, Amazon.CloudSearchDomain.Model.SearchRequest request) { Utils.Common.WriteVerboseEndpointMessage(this, client.Config, "Amazon CloudSearchDomain", "Search"); try { #if DESKTOP return client.Search(request); #elif CORECLR return client.SearchAsync(request).GetAwaiter().GetResult(); #else #error "Unknown build edition" #endif } catch (AmazonServiceException exc) { var webException = exc.InnerException as System.Net.WebException; if (webException != null) { throw new Exception(Utils.Common.FormatNameResolutionFailureMessage(client.Config, webException.Message), webException); } throw; } } #endregion internal class CmdletContext : ExecutorContext { public string ServiceUrl { get; set; } public String Cursor { get; set; } public String Expr { get; set; } public String Facet { get; set; } public String FilterQuery { get; set; } public String Highlight { get; set; } public Boolean? Partial { get; set; } public String Query { get; set; } public String QueryOptions { get; set; } public QueryParser QueryParser { get; set; } public String Return { get; set; } public Int64? Size { get; set; } public String Sort { get; set; } public Int64? Start { get; set; } public System.Func Select { get; set; } = (response, cmdlet) => response; } } }