첫 번째 API 호출 만들기

아티클
06/13/2024

이 페이지에서는 앱 및 게임에 대한 첫 번째 API 호출을 만드는 방법을 설명합니다.

API 호출 패턴

다음 다이어그램에서는 새 보고서 템플릿을 만들고, 사용자 지정 보고서를 예약하고, 실패 데이터를 검색하는 데 사용되는 API 호출 패턴을 보여 줍니다.

이 목록은 API 호출 패턴 다이어그램에 대한 자세한 정보를 제공합니다.

클라이언트 애플리케이션은 보고서 쿼리 만들기 API를 호출하여 사용자 지정 보고서 스키마/템플릿을 정의할 수 있습니다. 또는 시스템 쿼리 목록에서 보고서 템플릿 (QueryId) 을 사용할 수 있습니다.
성공하면 보고서 템플릿 만들기 API 는 .를 반환합니다 QueryId.
그런 다음 클라이언트 애플리케이션은 보고서 시작 날짜, 반복 간격, 되풀이 및 선택적 콜백 URI와 함께 보고서 만들기 API QueryID 를 호출합니다.
성공하면 보고서 만들기 API는 .를 반환합니다ReportID.
클라이언트 애플리케이션은 상태 API를 호출하여 보고서의 상태를 가져옵니다.
그런 다음 클라이언트 애플리케이션은 보고서 실행 가져오기 API를 사용하여 보고서 상태와 Report ID 날짜 범위를 쿼리합니다.
성공하면 보고서 다운로드 링크가 반환되고 애플리케이션에서 데이터 다운로드를 시작할 수 있습니다.

보고서 쿼리 언어 지정

보고서를 만드는 데 사용할 수 있는 시스템 쿼리를 제공하지만 비즈니스 요구 사항에 따라 사용자 고유의 쿼리를 만들 수도 있습니다. 사용자 지정 쿼리에 대한 자세한 내용은 사용자 지정 쿼리 사양을 참조하세요.

인증

먼저 Microsoft Store 분석 API 사용을 위한 필수 조건을 완료하여 파트너 센터 계정에 온보딩합니다. 다음으로 Microsoft Entra 액세스 토큰을 가져옵니다. 1단계와 2단계만 수행하세요. 3단계는 이 흐름에 중복됩니다.

프로그래매틱 API 호출

이전 섹션에 설명된 대로 Microsoft Entra 토큰을 가져온 후 다음 단계에 따라 첫 번째 프로그래밍 방식 액세스 보고서를 만듭니다.

다음 데이터 세트(datasetName)에서 데이터를 다운로드할 수 있습니다.

보고서 이름	API의 데이터 세트 이름
취득	취득
추가 기능 구입	AddOnAcquisitions
채널 및 변환	ChannelsAndConversions
게임패스 사용량	GamePass
Gamepass 성능	GamePassPurchase
상태: 충돌 및 이벤트	HealthFailureHits
설치	설치
등급	등급
검토	검토
지속 가능성	지속 가능성
사용량-일별	UsageDaily
사용량-월별	UsageMonthly
위시리스트	위시리스트
이벤트 참여	Xevents_Metrics
가격 책정 프로모션 - 유연한	Xprice_Flexible_Offer
가격 책정 프로모션 - 대상 지정	Xprice_Targeted_Offer

다음 섹션에서는 취득 데이터 세트의 콘텐츠에 프로그래밍 방식으로 액세스하는 방법의 예를 보여 줍니다.

데이터 세트 가져오기 API를 사용하여 REST 호출

API 응답은 보고서를 다운로드할 수 있는 데이터 세트 이름을 제공합니다. 특정 데이터 세트의 경우 API 응답은 사용자 지정 보고서 템플릿에 사용할 수 있는 선택 가능한 열 목록도 제공합니다.

보고서 쿼리 API 만들기

이 API는 열 및 메트릭을 내보내야 하는 데이터 세트를 정의하는 사용자 지정 쿼리를 만드는 데 도움이 됩니다. API는 비즈니스 요구 사항에 따라 새 보고 템플릿을 만들 수 있는 유연성을 제공합니다.

제공하는 시스템 쿼리를 사용할 수도 있습니다 . 사용자 지정 보고서 템플릿이 필요하지 않은 경우 제공하는 시스템 쿼리의 QueryIds를 사용하여 보고서 만들기 API를 직접 호출할 수 있습니다.

요청 예시

curl  
--location  
--request GET https://manage.devcenter.microsoft.com/consumer/insights/v1.1 /ScheduledDataset' \  
--header 'Authorization: Bearer <AzureADToken>'

응답 예제

{ 
    "value": [ 
        { 
            "columnFilters": {}, 
            "aggregationToDateRangeMapping": { 
                "Hourly": "LAST_72_HOURS", 
                "Daily": "LAST_30_DAYS,LAST_3_MONTHS", 
                "Weekly": "LAST_6_MONTHS,LAST_12_MONTHS", 
                "Monthly": "LAST_2_YEARS,LAST_3_YEARS,LAST_4_YEARS" 
            }, 
            "datasetName": "Acquisitions", 
            "selectableColumns": [ 
                "TitleId", 
                "ProductId", 
                "XboxProductId", 
                "ProductTypeName", 
                "TitleName", 
                "CatalogId", 
                "SandboxId", 
                "SkuId", 
                "SkuTypeName", 
                "SkuDisplayName", 
                "AvailabilityId", 
                "RegionName", 
                "CountryName", 
                "Market", 
                "PaymentType", 
                "StoreClientName", 
                "StoreClientCategory", 
                "ParentProductName", 
                "ParentProductId", 
                "XboxParentProductId", 
                "AcquisitionType", 
                "PurchaseTaxType", 
                "LocalCurrencyCode", 
                "SupportedPlatform", 
                "Age", 
                "Gender", 
                "OsVersion", 
                "DeviceType", 
                "DateStamp" 
            ], 
            "availableMetrics": [ 
                "PurchaseQuantity", 
                "PurchasePriceUSDAmount", 
                "PurchaseTaxUSDAmount", 
                "PurchasePriceLocalAmount", 
                "PurchaseTaxLocalAmount" 
            ], 
            "availableDateRanges": [ 
                "LAST_72_HOURS", 
                "LAST_30_DAYS", 
                "LAST_3_MONTHS", 
                "LAST_6_MONTHS", 
                "LAST_12_MONTHS", 
                "LAST_2_YEARS", 
                "LAST_3_YEARS", 
                "LAST_4_YEARS" 
            ], 
            "minimumRecurrenceInterval": 1 
        } 
}

사용자 지정 쿼리 만들기

이 단계에서는 원하는 보고서에 대한 사용자 지정 쿼리를 만듭니다. 만든 이 쿼리는 필요한 보고서(execute now 또는 schedule)가 있을 때마다 사용됩니다.

요청 예시

curl  
--location  
--request POST ' https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \  
--header ' Authorization: Bearer <AzureAD_Token>' \  
--header 'Content-Type: application/json' \  
--data-raw  
            '{  
    "Query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions WHERE ProductId IN ('all') TIMESPAN LAST_30_DAYS AGGREGATED Daily",  
    "Name": "Consumer public API Create query",  
    "Description": "Acquisition query creation."  
}'

응답 예제

{ 
    "value": [ 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "name": "Consumer public API Create query", 
            "description": "Acquisition query creation", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-03-26T11:26:48Z" 
        } 
    ], 
    "totalCount": 1, 
    "message": "Query created successfully", 
    "statusCode": 200 
}

쿼리 를 성공적으로 실행하면 보고서를 생성하는 데 사용해야 하는 queryId 가 생성됩니다.

쿼리 가져오기

사용 가능한 모든 쿼리를 나열합니다. 위의 단계에서 만든 기존 쿼리는 여기에 반영되어야 합니다.

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledQueries' \ 
--header 'Authorization: Bearer <token> \

응답 예제

{ 
    "value": [ 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "name": "Consumer public API Create query", 
            "description": "Acquisition query creation", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-03-26T11:26:48Z" 
        }, 
        { 
            "ProductInfo": { 
                "productGroupId": "", 
                "productId": "9PDC2J734M08", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "queryId": "724c796e-ea64-438f-b784-f2e284349d2f", 
            "name": "Acquisition_Daily_30days_next2months", 
            "description": null, 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, DateStamp, PurchaseQuantity, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "type": "userDefined", 
            "user": "", 
            "createdTime": "2024-01-23T17:21:42Z" 
        } 
    ], 
    "totalCount": 2, 
    "message": "Queries fetched successfully", 
    "statusCode": 200 
}

인스턴트 비동기 보고서 만들기

이 단계에서는 이전에 생성된 QueryId 를 사용하여 보고서를 만듭니다. 아래 쿼리는 이제 보고서를 실행하는 데 사용됩니다. 보고서 생성은 비동기이며 보고서를 페치하려면 별도의 API 호출이 필요합니다.

요청 예시

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer {{token}} \  
--header 'Content-Type: application/json' \ 
--data '{ 
"Description": "Acquisition report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create Report - Acquisition", 
"executeNow": true 
}'

응답 예제

{ 
    "value": [ 
        { 
            "productInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "reportId": "b58f9802-b118-485f-a0f1-edc273dea275", 
            "reportName": "Create Report - Acquisition", 
            "description": " Acquisition report ", 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "user": "", 
            "createdTime": "", 
            "modifiedTime": null, 
            "executeNow": true, 
            "queryStartTime": null, 
            "queryEndTime": null, 
            "startTime": "2024-03-26T11:33:16Z", 
            "reportStatus": "Active", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": "Report created successfully", 
    "statusCode": 200 
}

reportId: 'execution'이 생성됩니다. 이 ID는 보고서 다운로드를 예약하는 데 사용해야 합니다.

인스턴트 보고서 다운로드

요청 예시

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/b58f9802-b118-485f-a0f1-edc273dea275' \ 
--header 'Authorization: Bearer <token>' \

응답 예제

{ 
    "value": [ 
        { 
            "executionId": "28016f06-6bbf-459e-ba30-429da6910192", 
            "reportId": "b58f9802-b118-485f-a0f1-edc273dea275", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "executionStatus": "Completed", 
            "reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv", 
            "reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ", 
            "reportExpiryTime": null, 
            "reportGeneratedTime": "2024-03-26T11:46:19Z", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": null, 
    "statusCode": 200 
}

reportAccessSecureLink를 호출하여 보고서를 다운로드할 수 있습니다.

일정 보고서 만들기

API 호출은 일정 보고서를 만드는 데 도움이 될 수 있습니다.

Request

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer <token> \ 
--header 'Content-Type: application/json' \ 
--data '{ 
"Description": "Creating a scheduled report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create scheduled report - Acquisition", 
"StartTime": "2024-03-26T18:00:19Z", 
"RecurrenceCount": 49, 
"RecurrenceInterval": 1 
}'

Response

{ 
    "value": [ 
        { 
            "productInfo": { 
                "productGroupId": "", 
                "productId": "all", 
                "productIdDbColumnName": "ProductId" 
            }, 
            "reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f", 
            "reportName": "Create scheduled report - Acquisition", 
            "description": "Acquisition description", 
            "queryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
            "query": "SELECT TitleId, ProductId, XboxProductId, ProductTypeName, TitleName, CatalogId, SandboxId, SkuId, SkuTypeName, SkuDisplayName, AvailabilityId, RegionName, CountryName, Market, PaymentType, StoreClientName, StoreClientCategory, ParentProductName, ParentProductId, XboxParentProductId, AcquisitionType, PurchaseTaxType, LocalCurrencyCode, SupportedPlatform, Age, Gender, OsVersion, DeviceType, PurchasePriceUSDAmount, PurchaseTaxUSDAmount, PurchasePriceLocalAmount, PurchaseTaxLocalAmount FROM Acquisitions TIMESPAN LAST_30_DAYS AGGREGATED Daily", 
            "user": "", 
            "createdTime": "2024-03-26T11:38:20Z", 
            "modifiedTime": null, 
            "executeNow": false, 
            "queryStartTime": null, 
            "queryEndTime": null, 
            "startTime": "2024-03-26T18:00:19Z", 
            "reportStatus": "Active", 
            "recurrenceInterval": 1, 
            "recurrenceCount": 49, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "endTime": "2024-03-28T18:00:19Z", 
            "totalRecurrenceCount": 49, 
            "nextExecutionStartTime": "2024-03-26T17:00:19Z" 
        } 
    ], 
    "totalCount": 1, 
    "message": "Report created successfully", 
    "statusCode": 200 
}

보고서 상태 가져오기 및 세부 정보 다운로드

이제 보고서를 만들었으므로 보고서를 클라이언트에 다운로드할 수 있도록 API 호출을 통해 보고서 상태 및 다운로드 가능한 링크를 가져옵니다. 이 호출을 수행하려면 이전 단계에서 생성된 것과 동일한 reportId 를 사용하여 쿼리합니다.

Request

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport/execution/3b6c1ec2-53c2-48f6-9c9b-a46e5ca69d7d' \ 
--header 'Authorization: Bearer<token>' \

Response

{ 
    "value": [ 
        { 
            "executionId": "28016f06-6bbf-459e-ba30-429da6910192", 
            "reportId": "5e49796b-8146-4d98-9dde-aa14d2f78f0f", 
            "recurrenceInterval": -1, 
            "recurrenceCount": 1, 
            "callbackUrl": null, 
            "callbackMethod": null, 
            "format": "csv", 
            "executionStatus": "Completed", 
            "reportLocation": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv", 
            "reportAccessSecureLink": "https://pxanltx.blob.core.windows.net/programmatic-export-pi/Create Report - Acquisition.csv? <SAS token> ", 
            "reportExpiryTime": null, 
            "reportGeneratedTime": "2024-03-26T11:46:19Z", 
            "endTime": "2024-03-26T11:33:16Z", 
            "totalRecurrenceCount": 1, 
            "nextExecutionStartTime": null 
        } 
    ], 
    "totalCount": 1, 
    "message": null, 
    "statusCode": 200 
}

웹후크를 사용하여 일정 보고서 만들기

웹후크는 보고서가 준비되는 즉시 호출되는 엔드포인트로 작동합니다. callbackURL 매개 변수를 제공해야 합니다.

파트너는 웹후크 처리기를 작성해야 합니다. 이전 예제에서 보고서가 준비되면 'https://msnotify.com'이 알림으로 호출됩니다. 호출 시 파트너는 예약된 보고서 및 해당 상태 목록을 받은 다음 위에서 언급한 API를 사용하여 파일을 다운로드할 수 있습니다.

요청

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
--header 'Authorization: Bearer<token>' \ 
--header 'Content-Type: application/json' \ 
--header 'Cookie: ApplicationGatewayAffinity=3ebb3a6588e1f91ad543ccd7cdf31ec0; ApplicationGatewayAffinityCORS=3ebb3a6588e1f91ad543ccd7cdf31ec0' \ 
--data '{ 
"Description": "Acquisition report", 
"QueryId": "f17f8c8b-5980-40e0-a6f9-7df0c867b615", 
"ReportName": "Create scheduled report - Acquisition", 
"StartTime": "2024-03-26T18:00:19Z", 
"RecurrenceCount": 49, 
"RecurrenceInterval": 1, 
"callbackURL": "https://msnotify.com", 
"callbackMethod": "get" 
}'

API 문서

OpenAPI 사양을 참조하세요. 공용 Swagger 편집기에서 사양의 내용을 붙여넣어 API를 보고 기본 설정 언어(C#, python 등)로 클라이언트를 생성하여 API를 사용합니다.

Important

이 API는 executionStatus=Completed 및 getLatestExecution=true에 기본 쿼리 매개 변수가 설정되어 있습니다. 따라서 보고서를 처음 성공적으로 실행하기 전에 API를 호출하면 404 오류가 반환됩니다. 보류 중인 실행은 설정 executionStatus=Pending하여 가져올 수 있습니다.

다음을 통해 공유

첫 번째 API 호출 만들기

API 호출 패턴

보고서 쿼리 언어 지정

인증

프로그래매틱 API 호출

데이터 세트 가져오기 API를 사용하여 REST 호출

보고서 쿼리 API 만들기

요청 예시

응답 예제

사용자 지정 쿼리 만들기

요청 예시

응답 예제

쿼리 가져오기

응답 예제

인스턴트 비동기 보고서 만들기

요청 예시

응답 예제

인스턴트 보고서 다운로드

요청 예시

응답 예제

일정 보고서 만들기

Request

Response

보고서 상태 가져오기 및 세부 정보 다운로드

Request

Response

웹후크를 사용하여 일정 보고서 만들기

요청

API 문서

피드백

피드백

추가 리소스