Obter uma lista de clientes filtrada por um campo de pesquisaGet a list of customers filtered by a search field

Aplica-se aApplies To

  • Partner CenterPartner Center
  • Partner Center operado pela 21VianetPartner Center operated by 21Vianet
  • Partner Center do Microsoft Cloud GermanyPartner Center for Microsoft Cloud Germany
  • Partner Center do Microsoft Cloud for US GovernmentPartner Center for Microsoft Cloud for US Government

Obtém uma coleção de recursos do cliente que correspondem a um filtro.Gets a collection of Customer resources that match a filter. Opcionalmente, você pode definir um tamanho de página.You can optionally set a page size. Você pode filtrar por nome da empresa, domínio, revendedor indireto ou provedor de solução de nuvem indireta (CSP).You can filter by company name, domain, indirect reseller, or indirect cloud solution provider (CSP).

Pré-requisitosPrerequisites

  • Credenciais, conforme descrito em Autenticação do Partner Center.Credentials as described in Partner Center authentication. Esse cenário dá suporte à autenticação com aplicativos autônomos e aplicativos + credenciais de usuário.This scenario supports authentication with both standalone App and App+User credentials.

  • Um filtro construído pelo usuário.A user-constructed filter.

C#C#

Para obter uma coleção de clientes que correspondem a um filtro, primeiro crie uma instância de um objeto SimpleFieldFilter para criar o filtro.To get a collection of customers that match a filter, first instantiate a SimpleFieldFilter object to create the filter. Você precisará passar uma cadeia de caracteres que contém o CustomerSearchFielde indicar o tipo de operação de filtro como FieldFilterOperation. StartsWith.You'll need to pass a string that contains the CustomerSearchField, and indicate the type of filter operation as FieldFilterOperation.StartsWith. Essa é a única operação de filtro de campo com suporte do ponto de extremidade dos clientes.That's the only field filter operation supported by the customers end point. Você também precisará fornecer a cadeia de caracteres para filtrar por.You'll also need to provide the string to filter by.

Em seguida, crie uma instância de um objeto iQuery para passar para a consulta chamando o método BuildSimpleQuery e passando-o para o filtro.Next, instantiate an iQuery object to pass to the query by calling the BuildSimpleQuery method and passing it the filter. BuildSimplyQuery é apenas um dos tipos de consulta com suporte na classe QueryFactory .BuildSimplyQuery is just one of the query types supported by the QueryFactory class.

Por fim, para executar o filtro e obter o resultado, primeiro use IAggregatePartner. Customers para obter uma interface para as operações do cliente do parceiro.Finally, to execute the filter and get the result, first use IAggregatePartner.Customers to get an interface to the partner's customer operations. Em seguida, chame a consulta ou o método QueryAsync .Then call the Query or QueryAsync method.

IAggregatePartner partnerOperations;

// Specify the partial string to filter by (to match Contoso).
string searchPrefix = "cont"

// Create a simple field filter.
var fieldFilter = new SimpleFieldFilter(
    CustomerSearchField.CompanyName.ToString(),
    FieldFilterOperation.StartsWith,
    searchPrefix);

// Create an iQuery object to pass to the Query method.
var myQuery = QueryFactory.Instance.BuildSimpleQuery(fieldFilter);

// Get the collection of matching customers.
var customers = partnerOperations.Customers.Query(myQuery);

Exemplo: aplicativo de teste do console.Sample: Console test app. Projeto: classede exemplos do SDK do Partner Center: FilterCustomers.csProject: Partner Center SDK Samples Class: FilterCustomers.cs

Solicitação RESTREST request

Sintaxe da solicitaçãoRequest syntax

MétodoMethod URI da solicitaçãoRequest URI
GETGET {baseURL}/v1/Customers? tamanho = {tamanho} &filtro = {filtro} http/1.1{baseURL}/v1/customers?size={size}&filter={filter} HTTP/1.1

Parâmetros do URIURI parameters

Use os parâmetros de consulta a seguir.Use the following query parameters.

NomeName TipoType ObrigatórioRequired DescriçãoDescription
tamanhosize intint NãoNo O número de resultados a serem exibidos ao mesmo tempo.The number of results to be displayed at one time. Esse parâmetro é opcional.This parameter is optional.
filtrofilter filtrofilter SimYes O filtro para aplicar aos clientes.The filter to apply to customers. Deve ser uma cadeia de caracteres codificada.This must be an encoded string.

Sintaxe de FiltroFilter Syntax

Você deve compor o parâmetro de filtro como uma série de pares de chave-valor separados por vírgula.You must compose the filter parameter as a series of comma separated, key-value pairs. Cada chave e o valor devem ser individualmente entre aspas e separado por dois-pontos.Each key and value must be individually quoted and separated by a colon. Todo o filtro deve ser codificado.The entire filter must be encoded.

Um exemplo não codificado tem esta aparência: An unencoded example looks like this:

?filter{"Field":"CompanyName","Value":"cont","Operator":"starts_with"}

A tabela a seguir descreve os pares chave-valor necessários:The following table describes the required key-value pairs:

ChaveKey ValorValue
CampoField O campo para filtrar.The field to filter. Os valores válidos podem ser encontrados em CustomerSearchField.The valid values can be found in CustomerSearchField.
ValorValue O valor pelo qual filtrar.The value to filter by. O caso do valor é ignorado.The case of the value is ignored.
OperadorOperator O operador para aplicar.The operator to apply. O único valor com suporte para esse cenário de cliente é "começa _ com".The only supported value for this customer scenario is "starts_with".

Cabeçalhos de solicitaçãoRequest headers

Para obter mais informações, confira Cabeçalhos REST do Partner Center.For more information, see Partner Center REST headers.

Corpo da solicitaçãoRequest body

nenhuma.None.

Exemplo de solicitaçãoRequest example

GET https://api.partnercenter.microsoft.com/v1/customers?size=0&filter=%7B%22Field%22%3A%22CompanyName%22%2C%22Value%22%3A%22Cont%22%2C%22Operator%22%3A%22starts_with%22%7D HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 5ce66de5-eea9-486f-a11c-c852aa3d1502
MS-CorrelationId: a2a912ee-d595-47e2-97ae-1b0ae1efa13d
X-Locale: en-US
Host: api.partnercenter.microsoft.com
Connection: Keep-Alive

Resposta RESTREST response

Se for bem-sucedido, esse método retornará uma coleção de recursos de cliente correspondentes no corpo da resposta.If successful, this method returns a collection of matching Customer resources in the response body.

Códigos de êxito e de erro de respostaResponse success and error codes

Cada resposta vem com um código de status HTTP que indica êxito ou falha e informações de depuração adicionais.Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use uma ferramenta de rastreamento de rede para ler esse código, o tipo de erro e os parâmetros adicionais.Use a network trace tool to read this code, error type, and additional parameters. Para obter a lista completa, confira Códigos de erro REST do Partner Center.For the full list, see Partner Center REST error codes.

Exemplo de respostaResponse example

HTTP/1.1 200 OK
Content-Length: 1839
Content-Type: application/json; charset=utf-8
MS-CorrelationId: a2a912ee-d595-47e2-97ae-1b0ae1efa13d
MS-RequestId: dfeda56c-1af5-43fc-a9c0-346b9e85dc96
MS-CV: n0lMNyJtaUC802pO.0
MS-ServerId: 202010223
Date: Fri, 24 Feb 2017 22:08:20 GMT

{
    "totalCount": 3,
    "items": [{
            "id": "c5757d70-06f3-4f23-8367-5a9e55019f94",
            "companyProfile": {
                "tenantId": "c5757d70-06f3-4f23-8367-5a9e55019f94",
                "domain": "contoso190.onmicrosoft.com",
                "companyName": "Contoso190",
                "links": {
                    "self": {
                        "uri": "/customers/c5757d70-06f3-4f23-8367-5a9e55019f94/profiles/company",
                        "method": "GET",
                        "headers": []
                    }
                },
                "attributes": {
                    "objectType": "CustomerCompanyProfile"
                }
            },
            "relationshipToPartner": "reseller",
            "links": {
                "self": {
                    "uri": "/customers/c5757d70-06f3-4f23-8367-5a9e55019f94",
                    "method": "GET",
                    "headers": []
                }
            },
            "attributes": {
                "objectType": "Customer"
            }
        }, {
            "id": "7b26b357-9ca3-48b8-a58e-4febe2662a5d",
            "companyProfile": {
                "tenantId": "7b26b357-9ca3-48b8-a58e-4febe2662a5d",
                "domain": "ContosoCorpCo.onmicrosoft.com",
                "companyName": "Contoso",
                "links": {
                    "self": {
                        "uri": "/customers/7b26b357-9ca3-48b8-a58e-4febe2662a5d/profiles/company",
                        "method": "GET",
                        "headers": []
                    }
                },
                "attributes": {
                    "objectType": "CustomerCompanyProfile"
                }
            },
            "relationshipToPartner": "reseller",
            "links": {
                "self": {
                    "uri": "/customers/7b26b357-9ca3-48b8-a58e-4febe2662a5d",
                    "method": "GET",
                    "headers": []
                }
            },
            "attributes": {
                "objectType": "Customer"
            }
        }, {
            "id": "bfbd6ef0-311f-47ec-bbd7-0fcb7846661b",
            "companyProfile": {
                "tenantId": "bfbd6ef0-311f-47ec-bbd7-0fcb7846661b",
                "domain": "contosocorpdemo.onmicrosoft.com",
                "companyName": "Contoso",
                "links": {
                    "self": {
                        "uri": "/customers/bfbd6ef0-311f-47ec-bbd7-0fcb7846661b/profiles/company",
                        "method": "GET",
                        "headers": []
                    }
                },
                "attributes": {
                    "objectType": "CustomerCompanyProfile"
                }
            },
            "relationshipToPartner": "reseller",
            "links": {
                "self": {
                    "uri": "/customers/bfbd6ef0-311f-47ec-bbd7-0fcb7846661b",
                    "method": "GET",
                    "headers": []
                }
            },
            "attributes": {
                "objectType": "Customer"
            }
        }
    ],
    "links": {
        "self": {
            "uri": "/customers?size=0&filter=%7B%22Field%22%3A%22Domain%22%2C%22Value%22%3A%22cont%22%2C%22Operator%22%3A%22starts_with%22%7D",
            "method": "GET",
            "headers": []
        }
    },
    "attributes": {
        "objectType": "Collection"
    }
}