取得依搜尋欄位篩選的客戶清單

發行項
01/10/2024

適用於：合作夥伴中心 |由 21Vianet 營運的合作夥伴中心 |美國政府適用的 Microsoft Cloud 合作夥伴中心

取得符合篩選條件的客戶資源集合。您可以選擇性地設定頁面大小。您可以依公司名稱、網域、間接轉銷商或間接雲端解決方案提供者（CSP）進行篩選。

必要條件

認證，如合作夥伴中心驗證所述。此案例支援使用獨立應用程式和 App+使用者認證進行驗證。
用戶建構的篩選。

C#

若要取得符合篩選條件的客戶集合，請先具現化 SimpleFieldFilter 物件以建立篩選。您必須傳遞包含 CustomerSearchField 的字串串，並將篩選作業的類型指定為 FieldFilterOperation.StartsWith。 這是用戶端點支援的唯一欄位篩選作業。您也需要提供要篩選依據的字串。

接下來，藉由呼叫 BuildSimpleQuery 方法並將它傳遞至篩選，具現化 iQuery 物件以傳遞至查詢。 BuildSimplyQuery 只是 QueryFactory 類別支援的其中一個查詢類型。

最後，若要執行篩選並取得結果，請先使用 IAggregatePartner.Customers 來取得合作夥伴客戶作業的介面。然後呼叫 Query 或 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);

範例：控制台測試應用程式。專案：合作夥伴中心 SDK 範例類別：FilterCustomers.cs

REST 要求

要求語法

方法	要求 URI
GET	{baseURL}/v1/customers？size={size}&filter={filter} HTTP/1.1

URI 參數

使用下列查詢參數。

名稱	類型	必要	描述
size	int	No	要一次顯示的結果數目。這是選擇性參數。
篩選器	篩選器	Yes	要套用至客戶的篩選。這必須是編碼的字串。

篩選語法

您必須將篩選參數撰寫為一系列逗號分隔的索引鍵/值組。每個索引鍵和值都必須個別加上引號，並以冒號分隔。必須編碼整個篩選條件。

未編碼的範例如下所示：

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

下表描述必要的機碼/值群組：

機碼	值
欄位	要篩選的欄位。您可以在 CustomerSearchField 中找到有效值。
值	要篩選依據的值。會忽略值的案例。
運算子	要套用的運算符。此客戶案例唯一支援的值是「starts_with」。

要求標頭

如需詳細資訊，請參閱合作夥伴中心 REST 標頭。

要求本文

無。

要求範例

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

REST 回應

如果成功，這個方法會傳回回應本文中相符的客戶資源集合。

回應成功和錯誤碼

每個回應都隨附 HTTP 狀態碼，會指出成功與否以及其他的偵錯資訊。請使用網路追蹤工具來讀取此錯誤碼、錯誤類型和其他參數。如需完整清單，請參閱合作夥伴中心的 REST 錯誤碼。

回應範例

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"
    }
}

共用方式為