Obter um registro da atividade do Partner Center

Artigo
09/11/2024

Aplica-se a: Partner Center | Partner Center para o Microsoft Cloud for US Government

Este artigo descreve como recuperar um registro de operações que foram executadas por um usuário ou aplicativo parceiro durante um período de tempo.

Use essa API para recuperar registros de auditoria dos 30 dias anteriores a partir da data atual ou para um intervalo de datas especificado incluindo a data de início e/ou a data de término. Observe, no entanto, que, por motivos de desempenho, a disponibilidade de dados do log de atividades é limitada aos 90 dias anteriores. As solicitações com uma data de início superior a 90 dias antes da data atual receberão uma exceção de solicitação incorreta (código de erro: 400) e uma mensagem apropriada.

Pré-requisitos

Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário dá suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

C#

Para recuperar um registro das operações do Partner Center, primeiro estabeleça o intervalo de datas para os registros que você deseja recuperar. O exemplo de código a seguir usa apenas uma data de início, mas você também pode incluir uma data de término. Para obter mais informações, consulte o método Query. Em seguida, crie as variáveis necessárias para o tipo de filtro que deseja aplicar e atribua os valores apropriados. Por exemplo, para filtrar por subcadeia de caracteres do nome da empresa, crie uma variável para manter a subcadeia de caracteres. Para filtrar por ID do cliente, crie uma variável para manter a ID.

No exemplo a seguir, o código de exemplo é fornecido para filtrar por uma subcadeia de caracteres de nome da empresa, ID do cliente ou tipo de recurso. Escolha um e comente os outros. Em cada caso, você primeiro instancia um objeto SimpleFieldFilter usando seu construtor padrão para criar o filtro. Você precisará passar uma cadeia de caracteres que contenha o campo a ser pesquisado e o operador apropriado a ser aplicado, conforme mostrado. Você também deve fornecer a cadeia de caracteres pela qual filtrar.

Em seguida, use a propriedade AuditRecords para obter uma interface para auditar operações de registro e chame o método Query ou QueryAsync para executar o filtro e obter a coleção de AuditRecords que representam a primeira página do resultado. Passe ao método a data de início, uma data de término opcional não usada no exemplo aqui e um objeto IQuery que representa uma consulta em uma entidade. O objeto IQuery é criado passando o filtro criado acima para o método BuildSimpleQuery do QueryFactory.

Depois de ter a página inicial de itens, use o método Enumerators.AuditRecords.Create para criar um enumerador que você pode usar para iterar pelas páginas restantes.

// 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();
}

Exemplo: aplicativo de teste de console. Projeto: Pasta de exemplos do SDK do Partner Center: Auditoria

Solicitação REST

Sintaxe da solicitação

Método	URI da solicitação
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

Parâmetro do URI

Use os parâmetros de consulta a seguir ao criar a solicitação.

Nome	Digitar	Obrigatória	Descrição
startDate	date	Não	A data de início no formato aaaa-mm-dd. Se nenhum for fornecido, o conjunto de resultados será padronizado para 30 dias antes da data da solicitação. Este parâmetro é opcional quando um filtro é fornecido.
endDate	date	Não	A data de término no formato aaaa-mm-dd. Este parâmetro é opcional quando um filtro é fornecido. Quando a data de término é omitida ou definida como nula, a solicitação retorna a janela máxima ou usa hoje como a data de término, o que for menor.
filtro	string	Não	O filtro a ser aplicado. Esse parâmetro deve ser uma cadeia de caracteres codificada. Esse parâmetro é opcional quando a data de início ou a data de término são fornecidas.

Sintaxe de filtro

Você deve compor o parâmetro de filtro 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 esta aparência:

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

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

Chave	Valor
Campo	O campo para filtrar. Os valores com suporte podem ser encontrados na sintaxe Request.
Valor	O valor pelo qual filtrar. O uso de maiúsculas e minúsculas do valor é ignorado. Os seguintes parâmetros de valor são suportados, conforme mostrado na sintaxe Request: searchSubstring - Substitua pelo nome da empresa. Você pode inserir uma substring para corresponder a parte do nome da empresa (por exemplo, `bri` corresponderá `Fabrikam, Inc`a ). Exemplo: `"Value":"bri"` customerId - Substitua por uma cadeia de caracteres formatada em GUID que representa o identificador do cliente. Exemplo: `"Value":"0c39d6d5-c70d-4c55-bc02-f620844f3fd1"` resourceType - Substitua pelo tipo de recurso para o qual recuperar registros de auditoria (por exemplo, Assinatura). Os tipos de recursos disponíveis são definidos em ResourceType. Exemplo: `"Value":"Subscription"`
Operador	O operador para aplicar. Os operadores suportados podem ser encontrados na sintaxe Request.

Cabeçalhos da solicitação

Para obter mais informações, consulte Cabeçalhos REST do Parter Center.

Corpo da solicitação

Nenhum.

Exemplo de solicitação

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

Resposta REST

Se for bem-sucedido, esse método retornará um conjunto de atividades que atendem aos filtros.

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

Compartilhar via