Get a collection of invoices (Получение коллекции счетов клиента)
Область применения: Центр партнеров | Центр партнеров, управляемый 21Vianet | Центр партнеров для Microsoft Cloud for US Government
Как получить коллекцию счетов партнера.
Необходимые компоненты
- Учетные данные, описанные в статье о проверке подлинности в Центре партнеров. Этот сценарий поддерживает проверку подлинности с помощью автономных учетных данных приложения и приложения и пользователя.
C#
Чтобы получить коллекцию всех доступных счетов, используйте свойство "Счета", чтобы получить интерфейс для операций с счетами, а затем вызвать метод Get или GetAsync, чтобы получить коллекцию.
Чтобы получить страничные коллекции счетов, сначала вызовите метод BuildIndexedQuery и передайте его размер страницы для создания объекта IQuery. Затем используйте свойство Invoices, чтобы получить интерфейс для операций с счетом, а затем передать объект IQuery методу Query или QueryAsync, чтобы отправить запрос и получить первую страницу.
Затем используйте свойство "Перечислители", чтобы получить интерфейс к коллекции поддерживаемых перечислителей коллекций ресурсов, а затем вызвать Invoices.Create, чтобы создать перечислитель для обхода коллекции счетов. Наконец, используйте перечислитель для получения и работы с каждой страницей счетов, как показано в следующем примере кода. Каждый вызов метода Next отправляет запрос на следующую страницу счетов на основе размера страницы.
// IAggregatePartner partnerOperations;
// int invoicePageSize;
// Is this an unpaged or paged request?
bool isUnpaged = (this.invoicePageSize <= 0);
// If the scenario is unpaged, get all the invoices, otherwise get the first page.
var invoicesPage = (isUnpaged)
? partnerOperations.Invoices.Get()
: partnerOperations.Invoices.Query(QueryFactory.Instance.BuildIndexedQuery(this.invoicePageSize));
// Create an invoice enumerator for traversing the invoice pages.
var invoicesEnumerator = partnerOperations.Enumerators.Invoices.Create(invoicesPage);
int lineCounter = 1;
while (invoicesEnumerator.HasValue)
{
// Print the current invoice results page.
var invoices = invoicesEnumerator.Current.Items;
foreach (var i in invoices)
{
Console.WriteLine(String.Format("{0,3}. {1} {2} {3,16:C2}",
lineCounter++,
i.Id,
i.InvoiceDate.ToString("yyyy'-'MM'-'dd'T'HH':'mm':'ss'Z'"),
i.TotalCharges));
}
Console.WriteLine();
Console.Write("Press any key to retrieve the next invoices page");
Console.ReadKey();
// Get the next page of invoices.
invoicesEnumerator.Next();
}
Немного другой пример см. в примере: тестовое приложение консоли. Проект: Класс примеров пакета SDK Центра партнеров: GetPagedInvoices.cs
Примечание.
Тот же API используется для всех современных коммерческих покупок, а также 145p и лицензий Office. Размер и смещение учитываются только для устаревших счетов. Для всех современных коммерческих покупок страницы и смещения будут игнорироваться.
Запрос REST
Синтаксис запроса
| Способ | URI запроса |
|---|---|
| GET | {baseURL}/v1/invoices?size={size}&offset={offset} HTTP/1.1 |
| GET | {baseURL}/v1/invoices?size={size}&offset={offset}&filter={"LeftFilter":{"Field":{field},"Value":{value},"Operator":{operator},"RightFilter":"Field":{field},"Value":{value},"Operator":{operator},"Operator":{operator}} HTTP/1.1 |
Параметры универсального кода ресурса (URI)
При создании запроса используйте следующие параметры запроса.
| Имя. | Type | Обязательно | Описание |
|---|---|---|---|
| size | INT | No | Количество ресурсов счета, возвращаемых в ответе. Это необязательный параметр. |
| offset | INT | No | Отсчитываемый от нуля индекс первого счета для возврата. |
| Фильтр | строка | Нет | Текстовые критерии настраиваемого фильтра для уменьшения ресурсов счета в ответе. Используйте это условие, чтобы предотвратить ошибку времени ожидания. Узнайте , как использовать условие фильтра |
Использование условия фильтра
Пример условия фильтра:
/v1/invoices?size=10&offset=0&filter={"LeftFilter":{"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"},"RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"},"Operator":"Operator":"and"}
Критерии фильтра состоят из трех частей:
LeftFilter: первая конструкция фильтра, в которой указывается поле, значение и оператор для левой стороны выражения фильтра.
Поле: атрибут, используемый для фильтрации. Значение: значение атрибута
Например, "LeftFilter": {"Field":"InvoiceDate", "Value":"01/01/2023","Operator":"greater_than_or_equals"} означает, что вы хотите отфильтровать счета с датой счета или после 1 января 2023 года.
RightFilter: вторая конструкция фильтра, в которой указывается поле, значение и оператор для правой стороны выражения фильтра.
Например, RightFilter:{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} означает, что вы хотите отфильтровать счета с датой счета до 31 декабря 2023 года.
Оператор: логический оператор, соединяющий фильтры слева и справа. В качестве оператора можно использовать "и" или "или".
Например, "Оператор": "и" означает, что требуется фильтровать счета, соответствующие критериям фильтра слева и справа.
Чтобы использовать один фильтр, просто введите имя поля, значение и оператор. Нет необходимости в конструкции LeftFilter или RightFilter.
Заголовки запросов
Дополнительные сведения см. в статье о заголовках REST Центра партнеров.
Текст запроса
нет
Пример запроса
GET https://api.partnercenter.microsoft.com/v1/invoices?size=200&offset=0 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: e88d014d-ab70-41de-90a0-f7fd1797267d
MS-CorrelationId: de894e18-f027-4ac0-8b5a-34f0c222af0c
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com
Внимание
По состоянию на июнь 2023 г. последняя версия пакета SDK для .NET для Центра партнеров 3.4.0 теперь архивируется. Вы можете скачать выпуск пакета SDK из GitHub вместе с файлом чтения, содержащим полезные сведения.
Партнерам рекомендуется продолжать использовать REST API Центра партнеров.
Ответ REST
В случае успешного выполнения текст ответа содержит коллекцию ресурсов Счета .
Коды успешного выполнения и ошибок в ответе
Каждый ответ содержит код состояния HTTP, указывающий на успешность или сбой, а также другие сведения об отладке. Используйте средство трассировки сети для чтения этого кода, типа ошибки и других параметров. Полный список ответов есть в статье Коды ошибок REST в Центре партнеров.
Пример ответа
HTTP/1.1 200 OK
Content-Length: 256
Content-Type: application/json; charset=utf-8
MS-CorrelationId: 57eb2ca7-755f-450f-9187-eae1e75a0114
MS-RequestId: a45e6643-1caf-4429-8f90-07c03d85bc2b
Date: Thu, 24 Mar 2016 05:21:01 GMT
{
"totalCount": 2,
"items": [
{
"id": "D02005YFHI",
"invoiceDate": "2017-01-21T00:00:00Z",
"totalCharges": 24606.35,
"paidAmount": 1000,
"currencyCode": "GBP",
"currencySymbol": "£",
"pdfDownloadLink": "/invoices/D02005YFHI/documents/statement",
"taxReceipts": [
{
"id": "123456",
"taxReceiptPdfDownloadLink": "/invoices/D02005YFHI/receipts/123456/documents/statement"
}
],
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "office",
"links": {
"self": {
"uri": "/invoices/Recurring-D02005YFHI/lineitems/Office/BillingLineItems",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"documentType": "invoice",
"invoiceType": "Recurring",
"links": {
"self": {
"uri": "/invoices/Recurring-D02005YFHI",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Invoice"
}
},
{
"id": "G000024130",
"invoiceDate": "2018-02-08T01:22:47.603895Z",
"totalCharges": 586366,
"paidAmount": 0,
"currencyCode": "CHF",
"currencySymbol": "CHF",
"pdfDownloadLink": "/invoices/G000024130/documents/statement",
"taxReceipts": [
{
"id": "234567",
"taxReceiptPdfDownloadLink": "/invoices/G000024130/receipts/234567/documents/statement"
}
],
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "one_time",
"links": {
"self": {
"uri": "/invoices/OneTime-G000024130/lineitems/OneTime/BillingLineItems",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"amendments": [
{
"id": "G000024131",
"invoiceDate": "2018-02-08T18:44:37.5381456Z",
"totalCharges": 107661.12,
"paidAmount": 0,
"currencyCode": "CHF",
"currencySymbol": "CHF",
"invoiceDetails": [
{
"invoiceLineItemType": "billing_line_items",
"billingProvider": "one_time",
"attributes": {
"objectType": "InvoiceDetail"
}
}
],
"documentType": "adjustment_note",
"amendsOf": "G000024130",
"invoiceType": "OneTime",
"attributes": {
"objectType": "Invoice"
}
}
],
"documentType": "void_note",
"invoiceType": "OneTime",
"links": {
"self": {
"uri": "/invoices/OneTime-G000024130",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Invoice"
}
}
],
"links": {
"self": {
"uri": "/invoices?size=2&offset=0",
"method": "GET",
"headers": []
},
"next": {
"uri": "/invoices?size=2&offset=2",
"method": "GET",
"headers": []
}
},
"attributes": {
"objectType": "Collection"
}
}