파트너 센터 작업 레코드 가져오기

아티클
01/10/2024

적용 대상: 파트너 센터 | Microsoft Cloud for US Government 파트너 센터

이 문서에서는 일정 기간 동안 파트너 사용자 또는 애플리케이션에서 수행한 작업 레코드를 검색하는 방법을 설명합니다.

이 API를 사용하여 현재 날짜로부터 이전 30일 동안의 감사 레코드 또는 시작 날짜 및/또는 종료 날짜를 포함하여 지정된 날짜 범위에 대한 감사 레코드를 검색합니다. 그러나 성능상의 이유로 활동 로그 데이터 가용성은 이전 90일로 제한됩니다. 시작 날짜가 현재 날짜보다 90일 이전인 요청은 잘못된 요청 예외(오류 코드: 400)와 적절한 메시지를 받게 됩니다.

필수 조건

자격 증명(파트너 센터 인증에서 설명). 이 시나리오는 독립 실행형 앱 및 App+사용자 자격 증명을 모두 사용하여 인증을 지원합니다.

C#

파트너 센터 작업의 레코드를 검색하려면 먼저 검색하려는 레코드의 날짜 범위를 설정합니다. 다음 코드 예제에서는 시작 날짜만 사용하지만 종료 날짜를 포함할 수도 있습니다. 자세한 내용은 Query 메서드를 참조하세요. 다음으로 적용할 필터 형식에 필요한 변수를 만들고 적절한 값을 할당합니다. 예를 들어 회사 이름 부분 문자열을 필터링하려면 하위 문자열을 저장할 변수를 만듭니다. 고객 ID로 필터링하려면 ID를 저장할 변수를 만듭니다.

다음 예제에서는 회사 이름 부분 문자열, 고객 ID 또는 리소스 종류별로 필터링하기 위해 샘플 코드가 제공됩니다. 하나를 선택하고 다른 하나를 주석으로 처리합니다. 각 경우에 먼저 기본 생성자를 사용하여 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
GET	{baseURL}/v1/auditrecords?startDate={startDate}&endDate={endDate} HTTP/1.1
GET	{baseURL}/v1/auditrecords?startDate={startDate}&endDate={endDate}&filter={"Field":"CompanyName","Value":"{searchSubstring}","Operator":"substring"} HTTP/1.1
GET	{baseURL}/v1/auditrecords?startDate={startDate}&endDate={endDate}&filter={"Field":"CustomerId","Value":"{customerId}","Operator":"equals"} HTTP/1.1
GET	{baseURL}/v1/auditrecords?startDate={startDate}&endDate={endDate}&filter={"Field":"ResourceType","Value":"{resourceType}","Operator":"equals"} HTTP/1.1

URI 매개 변수

요청을 만들 때 다음 쿼리 매개 변수를 사용합니다.

이름	Type	필수	설명
startDate	date	아니요	yyyy-mm-dd 형식의 시작 날짜입니다. 아무 것도 제공되지 않으면 결과 집합은 기본적으로 요청 날짜 30일 이전으로 설정됩니다. 이 매개 변수는 필터가 제공될 때 선택 사항입니다.
endDate	date	아니요	종료 날짜(yyyy-mm-dd 형식)입니다. 이 매개 변수는 필터가 제공될 때 선택 사항입니다. 종료 날짜를 생략하거나 null로 설정하면 요청은 최대 창을 반환하거나 오늘을 종료 날짜로 사용합니다.
filter	string	아니요	적용할 필터입니다. 이 매개 변수는 인코딩된 문자열이어야 합니다. 이 매개 변수는 시작 날짜 또는 종료 날짜가 제공될 때 선택 사항입니다.

필터 구문

필터 매개 변수를 일련의 쉼표로 구분된 키-값 쌍으로 구성해야 합니다. 각 키와 값은 개별적으로 따옴표로 묶고 콜론으로 구분해야 합니다. 전체 필터를 인코딩해야 합니다.

인코딩되지 않은 예제는 다음과 같습니다.

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

다음 표에서는 필요한 키-값 쌍에 대해 설명합니다.

키	값
필드	필터링할 필드입니다. 지원되는 값은 요청 구문에서 찾을 수 있습니다.
값	필터링 기준 값입니다. 값의 대/소문자를 무시합니다. 요청 구문에 표시된 대로 다음 값 매개 변수가 지원됩니다. searchSubstring - 회사의 이름으로 바꿉니다. 부분 문자열을 입력하여 회사 이름의 일부와 일치시킬 수 있습니다(예 `bri` : 일치 `Fabrikam, Inc`). 예제`"Value":"bri"`: customerId - 고객 식별자를 나타내는 GUID 형식 문자열로 바꿉니다. 예제`"Value":"0c39d6d5-c70d-4c55-bc02-f620844f3fd1"`: resourceType - 감사 레코드를 검색할 리소스 유형(예: 구독)으로 바꿉니다. 사용 가능한 리소스 종류는 ResourceType에 정의되어 있습니다. 예제`"Value":"Subscription"`:
연산자	적용할 연산자입니다. 지원되는 연산자는 요청 구문에서 찾을 수 있습니다.

요청 헤더

자세한 내용은 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"
    }
}

다음을 통해 공유