Obter uma lista de clientes filtrada por um campo de pesquisa

Artigo
07/24/2024

Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center para o Microsoft Cloud for US Government

Obtém uma coleção de recursos do cliente que correspondem a um filtro. Opcionalmente, você pode definir um tamanho de página. Você pode filtrar por nome da empresa, domínio, revendedor indireto ou provedor de solução de nuvem indireto (CSP).

Pré-requisitos

Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.
Um filtro construído pelo usuário.

C#

Para obter uma coleção de clientes que correspondam a um filtro, primeiro instancie um objeto SimpleFieldFilter para criar o filtro. Você precisará passar uma cadeia de caracteres que contém o CustomerSearchField e indicar o tipo de operação de filtro como FieldFilterOperation.StartsWith. Essa é a única operação de filtro de campo suportada pelo ponto final do cliente. Você também precisará fornecer a cadeia de caracteres pela qual filtrar.

Em seguida, instancie um objeto iQuery para passar para a consulta chamando o método BuildSimpleQuery e passando-lhe o filtro. BuildSimplyQuery é apenas um dos tipos de consulta suportados pela classe QueryFactory .

Finalmente, para executar o filtro e obter o resultado, primeiro use IAggregatePartner.Customers para obter uma interface para as operações de cliente do parceiro. Em seguida, chame o método Query ou QueryAsync.

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 de console. Projeto: Exemplos de SDK do Partner Center Classe: FilterCustomers.cs

Solicitação REST

Sintaxe da solicitação

Método	URI da solicitação
GET	{baseURL}/v1/customers?size={size}&filter={filter} HTTP/1.1

Parâmetros do URI

Use os seguintes parâmetros de consulta.

Nome	Digitar	Obrigatória	Descrição
tamanho	int	Não	O número de resultados a serem exibidos ao mesmo tempo. Esse parâmetro é opcional.
filtro	filtro	Sim	O filtro para aplicar aos clientes. Isso deve ser uma cadeia de caracteres codificada.

Sintaxe de Filtro

Você deve compor o parâmetro filter como uma série de pares chave-valor separados por vírgula. Cada chave e o valor devem ser individualmente entre aspas e separado por dois-pontos. Todo o filtro deve ser codificado.

Um exemplo não codificado tem a seguinte aparência:

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

A tabela a seguir descreve os pares chave-valor necessários:

Chave	Valor
Campo	O campo para filtrar. Os valores válidos podem ser encontrados em CustomerSearchField.
Valor	O valor pelo qual filtrar. O caso do valor é ignorado.
Operador	O operador para aplicar. O único valor com suporte para esse cenário de cliente é "starts_with".

Cabeçalhos da solicitação

Para obter mais informações, confira Cabeçalhos REST do Partner Center.

Corpo da solicitação

Nenhum.

Exemplo de solicitação

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: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US
Host: api.partnercenter.microsoft.com
Connection: Keep-Alive

Resposta REST

Se bem-sucedido, esse método retorna uma coleção de recursos do Cliente correspondentes no corpo da resposta.

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica êxito ou falha e informações de depuração adicionais. Use uma ferramenta de rastreamento de rede para ler esse código, o tipo de erro e os parâmetros adicionais. Para obter a lista completa, confira Códigos de erro REST do Partner Center.

Exemplo de resposta

HTTP/1.1 200 OK
Content-Length: 1839
Content-Type: application/json; charset=utf-8
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
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": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
            "companyProfile": {
                "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
                "domain": "contoso190.onmicrosoft.com",
                "companyName": "Contoso190",
                "links": {
                    "self": {
                        "uri": "/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee/profiles/company",
                        "method": "GET",
                        "headers": []
                    }
                },
                "attributes": {
                    "objectType": "CustomerCompanyProfile"
                }
            },
            "relationshipToPartner": "reseller",
            "links": {
                "self": {
                    "uri": "/customers/aaaabbbb-0000-cccc-1111-dddd2222eeee",
                    "method": "GET",
                    "headers": []
                }
            },
            "attributes": {
                "objectType": "Customer"
            }
        }, {
            "id": "bbbbcccc-1111-dddd-2222-eeee3333ffff",
            "companyProfile": {
                "tenantId": "bbbbcccc-1111-dddd-2222-eeee3333ffff",
                "domain": "ContosoCorpCo.onmicrosoft.com",
                "companyName": "Contoso",
                "links": {
                    "self": {
                        "uri": "/customers/bbbbcccc-1111-dddd-2222-eeee3333ffff/profiles/company",
                        "method": "GET",
                        "headers": []
                    }
                },
                "attributes": {
                    "objectType": "CustomerCompanyProfile"
                }
            },
            "relationshipToPartner": "reseller",
            "links": {
                "self": {
                    "uri": "/customers/bbbbcccc-1111-dddd-2222-eeee3333ffff",
                    "method": "GET",
                    "headers": []
                }
            },
            "attributes": {
                "objectType": "Customer"
            }
        }, {
            "id": "ccccdddd-2222-eeee-3333-ffff4444aaaa",
            "companyProfile": {
                "tenantId": "ccccdddd-2222-eeee-3333-ffff4444aaaa",
                "domain": "contosocorpdemo.onmicrosoft.com",
                "companyName": "Contoso",
                "links": {
                    "self": {
                        "uri": "/customers/ccccdddd-2222-eeee-3333-ffff4444aaaa/profiles/company",
                        "method": "GET",
                        "headers": []
                    }
                },
                "attributes": {
                    "objectType": "CustomerCompanyProfile"
                }
            },
            "relationshipToPartner": "reseller",
            "links": {
                "self": {
                    "uri": "/customers/ccccdddd-2222-eeee-3333-ffff4444aaaa",
                    "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"
    }
}

Compartilhar via