請求書のコレクションを取得する

[アーティクル]
07/16/2024

適用対象: パートナーセンター | 21Vianet が運営するパートナーセンター | Microsoft Cloud for US Government のパートナーセンター

パートナーの請求書のコレクションを取得する方法。

前提条件

パートナーセンターの認証に関するページで説明している資格情報。このシナリオでは、スタンドアロンアプリとアプリ + ユーザーの両方の資格情報を使った認証がサポートされています。

C#

使用可能なすべての請求書のコレクションを取得するには、 Invoices プロパティを使用して請求書操作のインターフェイスを取得し、 Get または GetAsync メソッドを呼び出してコレクションを取得します。

請求書のページコレクションを取得するには、最初に BuildIndexedQuery メソッドを呼び出し、ページサイズを渡して IQuery オブジェクトを作成します。次に、 Invoices プロパティを使用して請求書操作へのインターフェイスを取得し、IQuery オブジェクトを Query または QueryAsync メソッドに渡して要求を送信し、最初のページを取得します。

次に、 Enumerators プロパティを使用して、サポートされているリソースコレクション列挙子のコレクションへのインターフェイスを取得し、 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&#39;-&#39;MM&#39;-&#39;dd&#39;T&#39;HH&#39;:&#39;mm&#39;:&#39;ss&#39;Z&#39;"),
            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();
}

少し異なる例については、「 サンプル: Console テストアプリ」を参照してください。 プロジェクト: パートナーセンター SDK サンプル Class: GetPagedInvoices.cs

Note

同じ 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 パラメーター

要求を作成するときは、次のクエリパラメーターを使用します。

名前	タイプ	Required	説明
size	int	いいえ	応答で返される請求リソースの数。このパラメータは任意です。
オフセット	int	いいえ	返される最初の請求書の 0 ベースのインデックス。
フィルター	string	いいえ	応答の請求書リソースを減らすためのテキストベースのカスタムフィルター条件。タイムアウトエラーを防ぐには、この条件を使用します。フィルター条件使用方法を参照してください

フィルター条件の使用方法

フィルター条件の例:

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

フィルター条件は、次の 3 つの部分で構成されます。

LeftFilter: フィルター式の左側のフィールド、値、および演算子を指定する最初のフィルターコンストラクト。

フィールド: フィルター処理に使用する属性。値: 属性の値

たとえば、"LeftFilter": {"Field":"InvoiceDate","Value":"01/01/2023","Operator":"greater_than_or_equals"} は、2023 年 1 月 1 日以降に請求書の日付を含む請求書をフィルター処理することを意味します。
RightFilter: 2 番目のフィルターコンストラクト。フィルター式の右側にフィールド、値、および演算子を指定します。

たとえば、"RightFilter":{"Field":"InvoiceDate","Value":"12/31/2023","Operator":"less_than_or_equals"} は、2023 年 12 月 31 日以前の請求書をフィルター処理することを意味します。
演算子: 左右のフィルターを接続する論理演算子。演算子として "and" または "or" を使用できます。

たとえば、"演算子": "and" は、左と右の両方のフィルター条件を満たす請求書をフィルター処理することを意味します。

1 つのフィルターを使用するには、フィールド名、値、および演算子を入力するだけです。 "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 年 6 月の時点で、最新のパートナーセンター .NET SDK リリース 3.4.0 がアーカイブされるようになりました。 SDK リリースは、有用な情報が記載された readme ファイルと一緒に GitHub からダウンロードできます。

パートナーの皆様には、パートナーセンター REST API を引き続き使用することをお勧めします。

REST 応答

成功した場合、応答本文には Invoice リソースのコレクションが含まれます。

応答の成功とエラーのコード

各応答には、成功または失敗とその他のデバッグ情報を示す 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"
    }
}

次の方法で共有