Obter um registo da atividade do Centro de Parceiros

Artigo
09/11/2024

Aplica-se a: Partner Center | Partner Center for 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 últimos 30 dias 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. No entanto, observe que, por motivos de desempenho, a disponibilidade de dados do log de atividades é limitada aos 90 dias anteriores. 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 na autenticação do Partner Center. Este cenário oferece 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 substring do nome da empresa, crie uma variável para manter a substring. Para filtrar por ID do cliente, crie uma variável para armazenar o 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 operações de registro de auditoria e chame o método Query ou QueryAsync para executar o filtro e obter a coleção de AuditRecord que representam a primeira página do resultado. Passe o 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

Pedido REST

Sintaxe da solicitação

Método	URI do pedido
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 URI

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

Nome	Type	Obrigatório	Description
startDate	data	Não	A data de início no formato aaaa-mm-dd. Se nenhum for fornecido, o conjunto de resultados será padrão para 30 dias antes da data da solicitação. Este parâmetro é opcional quando um filtro é fornecido.
endDate	data	Não	A data final 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.
filtrar	string	Não	O filtro a ser aplicado. Esse parâmetro deve ser uma cadeia de caracteres codificada. Este parâmetro é opcional quando a data de início ou a data de término são fornecidas.

Sintaxe do filtro

Você deve compor o parâmetro filter como uma série de pares chave-valor separados por vírgula. Cada chave e valor devem ser cotados individualmente e separados 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 chave-valor necessários:

Key	valor
Campo	O campo a filtrar. Os valores suportados podem ser encontrados em Sintaxe de solicitação.
Value	O valor pelo qual filtrar. O caso do valor é ignorado. Os seguintes parâmetros de valor são suportados, conforme mostrado na sintaxe de solicitação: 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 a candidatar. Os operadores suportados podem ser encontrados na sintaxe Request.

Cabeçalhos do pedido

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

Corpo do pedido

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 do REST

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

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso ou falha e informações adicionais de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e parâmetros adicionais. Para obter a lista completa, consulte 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"
    }
}

Partilhar via