取得合作夥伴中心活動的記錄

文章
09/11/2024

適用於：合作夥伴中心 |美國政府Microsoft雲端合作夥伴中心

本文說明如何擷取合作夥伴使用者或應用程式在一段時間內執行的作業記錄。

使用此 API 來擷取過去 30 天的稽核記錄，或包含開始日期和/或結束日期所指定的日期範圍。不過請注意，基於效能考慮，活動記錄數據可用性僅限於前90天。在目前日期之前的 90 天前，開始日期的要求會收到不正確的要求例外狀況（錯誤碼：400）和適當的訊息。

必要條件

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

C#

若要擷取合作夥伴中心作業的記錄，請先建立您要擷取之記錄的日期範圍。下列程式代碼範例只會使用開始日期，但您也可以包含結束日期。如需詳細資訊，請參閱 Query 方法。接下來，建立您要套用之篩選類型所需的變數，並指派適當的值。例如，若要依公司名稱子字串進行篩選，請建立變數來保存子字串。若要依客戶標識碼進行篩選，請建立變數來保存標識符。

在下列範例中，會提供範例程式代碼，以依公司名稱子字元串、客戶標識符或資源類型進行篩選。選擇一個並批注其他專案。在每個案例中，您會先使用其預設建構函式來具現化 SimpleFieldFilter 物件，以建立篩選。您必須傳遞包含要搜尋之字段的字串，以及要套用的適當運算元，如下所示。您也必須提供要篩選依據的字串。

接下來，使用 AuditRecords 屬性來取得用來稽核記錄作業的介面，並呼叫 Query 或 QueryAsync 方法來執行篩選，並取得代表結果第一頁的 AuditRecord 集合。傳遞方法開始日期、此處範例中未使用的選擇性結束日期，以及 代表實體查詢的 IQuery 物件。 IQuery 對像是藉由將上述建立的篩選傳遞至 QueryFactory 的 BuildSimpleQuery 方法所建立。

一旦您擁有專案的初始頁面，請使用 Enumerators.AuditRecords.Create 方法來建立列舉值，讓您可用來逐一查看其餘頁面。

// IAggregatePartner partnerOperations;

var startDate = new DateTime(DateTime.Now.Year, DateTime.Now.Month, 01);

// First perform the query, then get the enumerator. Choose one of the following and comment out the other two.

// To retrieve audit records by company name substring (for example "bri" matches "Fabrikam, Inc.").
var searchSubstring="bri";
var filter = new SimpleFieldFilter(AuditRecordSearchField.CompanyName.ToString(), FieldFilterOperation.Substring, searchSubstring);
var auditRecordsPage = partnerOperations.AuditRecords.Query(startDate.Date, query: QueryFactory.Instance.BuildSimpleQuery(filter));

// To retrieve audit records by customer ID.
var customerId="0c39d6d5-c70d-4c55-bc02-f620844f3fd1";
var filter = new SimpleFieldFilter(AuditRecordSearchField.CustomerId.ToString(), FieldFilterOperation.Equals, customerId);
var auditRecordsPage = partnerOperations.AuditRecords.Query(startDate.Date, query: QueryFactory.Instance.BuildSimpleQuery(filter));

// To retrieve audit records by resource type.
int resourceTypeInt = 3; // Subscription Resource.
string searchField = Enum.GetName(typeof(ResourceType), resourceTypeInt);
var filter = new SimpleFieldFilter(AuditRecordSearchField.ResourceType.ToString(), FieldFilterOperation.Equals, searchField);
var auditRecordsPage = partnerOperations.AuditRecords.Query(startDate.Date, query: QueryFactory.Instance.BuildSimpleQuery(filter));

var auditRecordEnumerator = partnerOperations.Enumerators.AuditRecords.Create(auditRecordsPage);

int pageNumber = 1;
while (auditRecordEnumerator.HasValue)
{
    // Work with the current page.
    foreach (var c in auditRecordEnumerator.Current.Items)
    {
        // Display some info, such as operation type, operation date, and operation status.
        Console.WriteLine(string.Format("{0} {1} {2}.", c.OperationType, c.OperationDate, c.OperationStatus));
    }

    // Get the next page of audit records.
    auditRecordEnumerator.Next();
}

範例：控制台測試應用程式。專案：合作夥伴中心 SDK 範例 資料夾：稽核

REST 要求

要求語法

方法	要求 URI
GET	{baseURL}/v1/auditrecords？startDate={startDate} HTTP/1.1
取得	{baseURL}/v1/auditrecords？startDate={startDate}&endDate={endDate} HTTP/1.1
取得	{baseURL}/v1/auditrecords？startDate={startDate}&endDate={endDate}&filter={“Field”：“CompanyName”，“Value”：“{searchSubstring}”，“Operator”：“substring”} HTTP/1.1
取得	{baseURL}/v1/auditrecords？startDate={startDate}&endDate={endDate}&filter={“Field”：“CustomerId”，“Value”：“{customerId}”，“Operator”：“equals”} HTTP/1.1
取得	{baseURL}/v1/auditrecords？startDate={startDate}&endDate={endDate}&filter={“Field”：“ResourceType”，“Value”：“{resourceType}”，“Operator”：“equals”} HTTP/1.1

URI 參數

建立要求時，請使用下列查詢參數。

名稱	類型	必要	描述
startDate	date	No	yyyy-mm-dd 格式的開始日期。如果未提供任何項目，結果集會預設為要求日期之前的 30 天。提供篩選條件時，這個參數是選擇性的。
endDate	date	No	yyyy-mm-dd 格式的結束日期。提供篩選條件時，這個參數是選擇性的。當省略結束日期或設定為 null 時，要求會傳回 max 視窗，或使用今天做為結束日期，無論哪一個比較少。
篩選器	字串	No	要套用的篩選條件。此參數必須是編碼的字串。提供開始日期或結束日期時，這個參數是選擇性的。

篩選語法

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

未編碼的範例如下所示：

?filter{"Field":"CompanyName","Value":"bri","Operator":"substring"}

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

機碼	值
欄位	要篩選的欄位。您可以在 Request 語法中找到支援的值。
值	要篩選依據的值。會忽略值的案例。支援下列值參數，如要求語法所示： searchSubstring - 以公司名稱取代。您可以輸入子字串來比對公司名稱的一部分（例如， `bri` 將會相符 `Fabrikam, Inc`）。範例： `"Value":"bri"` customerId - 以代表客戶識別子的 GUID 格式字串取代。範例： `"Value":"0c39d6d5-c70d-4c55-bc02-f620844f3fd1"` resourceType - 將取代為要擷取稽核記錄的資源類型（例如訂用帳戶）。可用的資源類型定義於 ResourceType 中。範例： `"Value":"Subscription"`
運算子	要套用的運算符。您可以在 Request 語法中找到支持的運算子。

要求標頭

如需詳細資訊，請參閱 Parter Center REST 標頭。

要求本文

無。

要求範例

GET https://api.partnercenter.microsoft.com/v1/auditrecords?startDate=6/1/2017%2012:00:00%20AM&filter=%7B%22Field%22:%22CustomerId%22,%22Value%22:%220c39d6d5-c70d-4c55-bc02-f620844f3fd1%22,%22Operator%22:%22equals%22%7D HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 127facaa-e389-41f8-8bb7-1d1af99db893
MS-CorrelationId: de9c2ccc-40dd-4186-9660-65b9b64c3d14
X-Locale: en-US
Host: api.partnercenter.microsoft.com
Connection: Keep-Alive

REST 回應

如果成功，這個方法會傳回一組符合篩選的活動。

回應成功和錯誤碼

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

回應範例

HTTP/1.1 200 OK
Content-Length: 2859
Content-Type: application/json; charset=utf-8
MS-CorrelationId: de9c2ccc-40dd-4186-9660-65b9b64c3d14
MS-RequestId: 127facaa-e389-41f8-8bb7-1d1af99db893
MS-CV: 4xDKynq/zE2im0wj.0
MS-ServerId: 030011719
Date: Tue, 27 Jun 2017 22:19:46 GMT

{
    "totalCount": 2,
    "items": [{
            "partnerId": "3b33e682-00c3-41ee-9dd2-a548adf56438",
            "customerId": "0c39d6d5-c70d-4c55-bc02-f620844f3fd1",
            "customerName": "Relecloud",
            "userPrincipalName": "admin@domain.onmicrosoft.com",
            "resourceType": "order",
            "resourceNewValue": "{\"Id\":\"d51a052e-043c-4a2a-aa37-2bb938cef6c1\",\"ReferenceCustomerId\":\"0c39d6d5-c70d-4c55-bc02-f620844f3fd1\",\"BillingCycle\":\"none\",\"LineItems\":[{\"LineItemNumber\":0,\"OfferId\":\"C0BD2E08-11AC-4836-BDC7-3712E744922F\",\"SubscriptionId\":\"488745B5-2086-4912-802C-6ABB9F7C3638\",\"ParentSubscriptionId\":null,\"FriendlyName\":\"Office 365 Business Premium Trial\",\"Quantity\":25,\"PartnerIdOnRecord\":null,\"Links\":{\"Subscription\":{\"Uri\":\"/customers/0c39d6d5-c70d-4c55-bc02-f620844f3fd1/subscriptions/488745B5-2086-4912-802C-6ABB9F7C3638\",\"Method\":\"GET\",\"Headers\":[]}}}],\"CreationDate\":\"2017-06-15T15:56:04.077-07:00\",\"Links\":{\"Self\":{\"Uri\":\"/customers/0c39d6d5-c70d-4c55-bc02-f620844f3fd1/orders/d51a052e-043c-4a2a-aa37-2bb938cef6c1\",\"Method\":\"GET\",\"Headers\":[]}},\"Attributes\":{\"Etag\":\"eyJpZCI6ImQ1MWEwNTJlLTA0M2MtNGEyYS1hYTM3LTJiYjkzOGNlZjZjMSIsInZlcnNpb24iOjF9\",\"ObjectType\":\"Order\"}}",
            "operationType": "create_order",
            "operationDate": "2017-06-15T22:56:05.0589308Z",
            "operationStatus": "succeeded",
            "customizedData": [{
                    "key": "OrderId",
                    "value": "d51a052e-043c-4a2a-aa37-2bb938cef6c1"
                }, {
                    "key": "BillingCycle",
                    "value": "None"
                }, {
                    "key": "OfferId-0",
                    "value": "C0BD2E08-11AC-4836-BDC7-3712E744922F"
                }, {
                    "key": "SubscriptionId-0",
                    "value": "488745B5-2086-4912-802C-6ABB9F7C3638"
                }, {
                    "key": "SubscriptionName-0",
                    "value": "Office 365 Business Premium Trial"
                }, {
                    "key": "Quantity-0",
                    "value": "25"
                }, {
                    "key": "PartnerOnRecord-0",
                    "value": null
                }
            ],
            "attributes": {
                "objectType": "AuditRecord"
            }
        }, {
            "partnerId": "3b33e682-00c3-41ee-9dd2-a548adf56438",
            "customerId": "0c39d6d5-c70d-4c55-bc02-f620844f3fd1",
            "customerName": "Relecloud",
            "userPrincipalName": "admin@domain.onmicrosoft.com",
            "applicationId": "Partner Center Native App",
            "resourceType": "license",
            "resourceNewValue": "{\"LicensesToAssign\":[{\"ExcludedPlans\":null,\"SkuId\":\"efccb6f7-5641-4e0e-bd10-b4976e1bf68e\"}],\"LicensesToRemove\":null,\"LicenseWarnings\":[],\"Attributes\":{\"ObjectType\":\"LicenseUpdate\"}}",
            "operationType": "update_customer_user_licenses",
            "operationDate": "2017-06-01T20:09:07.0450483Z",
            "operationStatus": "succeeded",
            "customizedData": [{
                    "key": "CustomerUserId",
                    "value": "482e2152-4b49-48ec-b715-823365ce3d4c"
                }, {
                    "key": "AddedLicenseSkuId",
                    "value": "efccb6f7-5641-4e0e-bd10-b4976e1bf68e"
                }
            ],
            "attributes": {
                "objectType": "AuditRecord"
            }
        }
    ],
    "links": {
        "self": {
            "uri": "/auditrecords?startDate=2017-06-01&size=500&filter=%7B%22Field%22%3A%22CustomerId%22%2C%22Value%22%3A%220c39d6d5-c70d-4c55-bc02-f620844f3fd1%22%2C%22Operator%22%3A%22equals%22%7D",
            "method": "GET",
            "headers": []
        }
    },
    "attributes": {
        "objectType": "Collection"
    }
}

分享方式：