Nouvelle API v2 d’utilisation quotidienne du commerce (bêta)
S’applique à : Espace partenaires | Espace partenaires géré par 21Vianet | Espace partenaires de Microsoft Cloud for US Government
Utilisez ces API pour obtenir de nouvelles données d’utilisation quotidiennes facturées et non facturées au commerce de manière asynchrone.
Remarque
Cette API sera bientôt déconseillée. Pour garantir des opérations transparentes, nous vous recommandons de migrer vers la version en disponibilité générale. Voici les détails que vous devez planifier à l’avance :
Objectif : Récupérer les éléments de ligne d’utilisation facturés tous les jours pour les périodes de facturation de septembre 2022 avant le 21 janvier 2025.
Action : utilisez cette API, mais migrez vers la disponibilité générale v2 dès que possible.
Objectif : Récupérer les éléments de ligne d’utilisation facturés tous les jours pour les périodes de facturation de septembre 2022 à partir du 21 janvier 2025.
Action : Utilisez uniquement l’API v2 GA.
Objectif : Récupérer les éléments de ligne d’utilisation quotidiens non facturés pour les périodes de facturation actuelles et précédentes avant le 21 janvier 2025.
Action : utilisez cette API, mais migrez vers la disponibilité générale v2 dès que possible.
Objectif : Récupérez les éléments de ligne d’utilisation quotidiens non facturés pour les périodes de facturation actuelles et précédentes du 21 janvier 2025.
Action : Utilisez uniquement l’API v2 GA.
Pour une transition transparente vers les nouvelles API, suivez ce lien : API de rapprochement d’utilisation facturée et non facturée par jour v2 (GA).
Merci pour votre attention, et nous nous réjouissons de votre réussite continue avec nos API de facturation.
Remarque
Vous pouvez accéder à vos éléments de ligne d’utilisation quotidiens non facturés via l’API ou le portail de l’Espace partenaires. Pour garantir des données précises, autorisez jusqu’à 24 heures de disponibilité. Selon votre emplacement et lorsque les compteurs signalent l’utilisation, il peut y avoir d’autres retards.
Nous hiérarchisons d’abord la remise du temps des données d’utilisation facturées par jour. Parfois, vous ne voyez peut-être pas les données d’utilisation quotidiennes non facturées les plus récentes jusqu’à ce que les données d’utilisation facturées du mois précédent soient disponibles. Une fois que vous avez reçu les données d’utilisation facturées, vous pouvez ensuite récupérer toutes les données d’utilisation non facturées mises à jour à partir du début du mois.
Votre compréhension et votre patience sont appréciées, car nous nous efforçons de fournir les informations les plus précises et les plus rapides possibles.
Important
Les données d’utilisation évaluées quotidiennement n’incluent pas les frais pour ces produits :
- Réservation Azure
- Plan d’épargne Azure
- Office
- Dynamics
- Microsoft Power Apps
- Logiciels perpétuels
- Abonnement logiciel
- Produit SaaS non Microsoft ou marketplace
Présentation de l’API
L’API asynchrone est une nouvelle méthode permettant d’accéder rapidement aux données de facturation et de rapprochement en blocs gérables. Il élimine la nécessité de maintenir une connexion ouverte pendant des heures et de parcourir des millions de transactions de manière itérative.
Nous utilisons des modèles de clé de valet et de réponse de requête asynchrone pour optimiser nos API de facturation et de rapprochement pour fournir les résultats de manière asynchrone. Les réponses d’API fournissent un jeton pour accéder aux données de rapprochement avec tous les attributs ou un sous-ensemble.
Vous pouvez télécharger les données d’utilisation de manière asynchrone à l’aide de trois nouvelles étapes (points de terminaison d’API). Pour en savoir plus, lisez les sections suivantes :
Point de terminaison de ligne d’utilisation
Utilisez cette API pour accéder aux éléments de ligne de consommation facturés ou non facturés. Elle retourne un état HTTP 202 et un en-tête d’emplacement avec l’URL, que vous devez interroger à intervalles réguliers jusqu’à ce que vous receviez un état de réussite avec une URL de manifeste.
Point de terminaison d’état de l’opération
Jusqu’à ce que vous receviez l’état de réussite, continuez à interroger cette API à intervalles réguliers. Si les données demandées ne sont pas disponibles, la réponse de l’API inclut un en-tête Retry-After indiquant la durée pendant laquelle vous devez attendre avant d’envoyer une autre requête.
Point de terminaison de manifeste
Ce point de terminaison fournit un dossier de stockage à partir duquel les données de facturation réelles peuvent être téléchargées. La réponse fractionne ou partitionne les fichiers pour optimiser le débit et le parallélisme d’E/S.
Diagramme de séquence
Le diagramme illustre les étapes nécessaires pour télécharger les données de rapprochement.
Séquence d’actions utilisateur
Procédez comme suit pour récupérer les données de rapprochement.
Étape 1 : Envoyer une demande
Envoyez une requête POST au point de terminaison de l’API.
Obtenir des éléments de ligne d’utilisation non facturés
Obtenez des éléments de ligne d’utilisation non facturés pour le mois calendrier actuel ou le dernier mois calendrier.
Requête d’API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Paramètres de la demande
| Nom | Dans | Obligatoire | Type | Description |
|---|---|---|---|---|
| fragment | Requête | False | Chaîne | Choisissez « full » pour une réponse complète ou « de base » pour un sous-ensemble d’attributs. La valeur par défaut est « full ». Consultez la liste des attributs de cet article. |
| period | Requête | True | Chaîne | Utilisez « actuel » ou « dernier » pour obtenir l’utilisation pour le mois calendrier actuel ou le dernier mois. La valeur « last » est la même que « précédente » dans les API V1 existantes. |
| currencyCode | Requête | True | Chaîne | Code monétaire de facturation du partenaire. |
Paramètres de requête déconseillés
La version plus récente de l’API ne nécessite pas les paramètres d’URI suivants :
| Nom | Description |
|---|---|
| Fournisseur | N/A. (Elle retourne toute l’utilisation du plan Azure et équivaut à « onetime » des API V1 existantes.) |
| hasPartnerEarnedCredit | N/A. (retourne toutes les données, indépendamment de PEC.) |
| Taille | N/A. |
| Contrepartie | N/A. |
| seekOperation | N/A. |
En-tête de requête
Consultez la liste des en-têtes de requête pour l’API dans cet article.
Corps de la demande
N/A.
Réponse de l’API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
L’API retourne l’état HTTP 202. En fonction de la demande, l’API peut retourner un autre état standard.
| Nom | Description |
|---|---|
| 202 Accepté | La demande est acceptée. Interrogez l’URL d’en-tête de l’emplacement de l’opération pour obtenir l’état de la demande. |
Obtenir les éléments de ligne d’utilisation facturés
Obtenez les éléments de ligne d’utilisation facturés pour la période de facturation fermée.
Requête d’API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Paramètres de la demande
| Nom | Dans | Obligatoire | Type | Description |
|---|---|---|---|---|
| invoiceId | Chemin d’accès | True | Chaîne | Numéro de facture de l’Espace partenaires. |
| Fragment | Requête | False | Chaîne | Choisissez « full » pour une réponse complète ou « de base » pour un sous-ensemble d’attributs. La valeur par défaut est « full ». Consultez la liste des attributs de cet article. |
Paramètres de requête déconseillés
La version plus récente de l’API ne nécessite pas les paramètres d’URI suivants :
| Nom | Description |
|---|---|
| Fournisseur | N/A. (Elle retourne toute l’utilisation du plan Azure et équivaut à « onetime » des API V1 existantes.) |
| hasPartnerEarnedCredit | N/A. (retourne toutes les données, indépendamment de PEC.) |
| Taille | N/A. |
| Contrepartie | N/A. |
| seekOperation | N/A. |
En-tête de requête
Consultez la liste des en-têtes de requête pour l’API dans cet article.
Corps de la demande
N/A.
Réponse de l’API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
L’API retourne « HTTP 202 Accepté ». En fonction de l’API de requête, vous pouvez retourner un autre état standard.
| Nom | Description |
|---|---|
| 202 Accepté | La demande est acceptée. Vérifiez l’état de la demande en interrogeant l’URL d’en-tête d’emplacement de l’opération. |
Étape 2 : Vérifier l’état de la demande
Attendez un HTTP 200 avec un état de terminal ayant réussi ou échoué. L’URL du manifeste est « resourceLocation » dans l’état de réussite.
Obtenir l’état d’une opération
Obtient l’état d’une demande de données de rapprochement.
Requête d’API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Paramètres de la demande
| Nom | Dans | Obligatoire | Type | Description |
|---|---|---|---|---|
| operationId | Chemin d’accès | True | Chaîne | ID de l’opération. |
En-tête de requête
Consultez la liste des en-têtes de requête pour l’API dans cet article.
Corps de la demande
N/A.
État de la réponse
En plus de l’état HTTP standard de cet article, l’API peut retourner cet état HTTP :
| Nom | Description |
|---|---|
| 410 Supprimé | Chaque lien d’opération est actif pendant une quantité spécifiée de temps contrôlé par le serveur. Une fois le temps écoulé, le client doit envoyer une nouvelle demande. |
Charge utile de réponse
La charge utile de réponse de l’API retourne les attributs suivants :
| Nom | Facultatif | Description |
|---|---|---|
| createdDateTime | false | Heure de la demande. |
| lastActionDateTime | false | Heure de modification de l’état. |
| resourceLocation | true | URI de charge utile du manifeste. |
| statut | false | Valeurs et actions possibles. |
| Valeur | Action du client |
|---|---|
| non démarrage | Effectuez un autre appel pour vérifier l’état après avoir attendu l’heure spécifiée dans l’en-tête « Retry-After ». |
| exécution en cours | Effectuez un autre appel pour vérifier l’état après avoir attendu l’heure spécifiée dans l’en-tête « Retry-After ». |
| succeeded | État final de l’opération, qui indique que les données sont prêtes. Récupérez la charge utile du manifeste à l’aide de l’URI spécifié dans resourceLocation. |
| échec | État du terminal, qui indique une défaillance permanente. Redémarrez l’opération. |
Pour l’attribut d’erreur :
| Nom | Facultatif | Description |
|---|---|---|
| error | true | Détails de l’erreur fournis au format json si l’état de l’opération a échoué. |
| Nom | Facultatif | Description |
|---|---|---|
| message | false | Décrit l’erreur en détail |
| code | false | Indique le type d’erreur qui s’est produite |
Requête d’API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Réponse de l’API
La réponse suggère d’attendre 10 secondes avant de réessayer lors du traitement des données.
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
Requête d’API
(10 secondes après la demande précédente)
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Réponse de l’API
L’API retourne l’état « réussi » et l’URI « resourceLocation ».
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Étape 3 : Obtenir la charge utile du manifeste
L’appelant effectue une requête GET à l’URL du manifeste pour en savoir plus sur l’emplacement où les données de rapprochement sont stockées dans les objets blob Azure.
Obtention du manifeste
Récupère le manifeste contenant des informations sur l’emplacement de stockage Azure des données de rapprochement.
Requête d’API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Paramètres de la demande
| Nom | Dans | Obligatoire | Type | Description |
|---|---|---|---|---|
| manifestId | Chemin d’accès | True | Chaîne | ID de manifeste. |
En-tête de requête
Consultez la [liste des en-têtes de requête pour l’API] dans cet article.
Corps de la demande
N/A.
État de la réponse
En plus de l’état HTTP standard, l’API peut retourner cet état HTTP :
| Nom | Description |
|---|---|
| 410 Supprimé | Chaque lien manifeste est actif pendant une quantité spécifiée de temps contrôlé par le serveur. Une fois le temps écoulé, le client doit envoyer une nouvelle demande. |
Charge utile de réponse
La réponse de l’API retourne les attributs suivants :
| Nom | Description |
|---|---|
| Version | Version du schéma de manifeste. |
| dataFormat | Format du fichier de données de facturation. Valeurs possibles compresséesJSONLines : chaque objet blob est un fichier compressé et les données du fichier sont au format de lignes JSON. Pour accéder aux données, décompressez le fichier. |
| utcCreatedDateTime | Heure de création du fichier manifeste. |
| eTag | Version des données du manifeste. Une modification des informations de facturation génère une nouvelle valeur eTag. |
| partnerTenantId | ID de locataire partenaire. |
| rootFolder | Répertoire racine du fichier. |
| rootFolderSAS | Jeton SAP pour accéder au fichier. |
| partitionType | Cette propriété divise les données. Si une partition donnée a plus que le nombre pris en charge, les données sont divisées en plusieurs fichiers correspondant à « partitionValue ». Par défaut, le système partitionne les données en fonction du nombre d’éléments de ligne dans le fichier. Ne définissez pas un nombre fixe d’éléments de ligne ou de taille de fichier dans votre code, car le principe de partitionnement peut changer. |
| blobCount | Nombre total de fichiers pour cet ID de locataire partenaire. |
| sizeInBytes | Nombre total d’octets dans tous les fichiers. |
| blobs | Tableau JSON d’objets « blob » ayant les détails de tous les fichiers de l’ID de locataire partenaire. |
| Objet Blob | |
| Nom | Nom de l’objet blob. |
| sizeInBytes | Taille de l’objet blob en octets. |
| partitionValue | Partition qui contient le fichier. Une partition volumineuse sera divisée en plusieurs fichiers, chacun avec le même « partitionValue ». |
Exemple de charge utile de manifeste
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
Étape 4 : Télécharger les données de rapprochement d’utilisation à partir de l’emplacement de stockage
Obtenez le jeton SAP et l’emplacement de stockage d’objets blob à partir de propriétés « rootFolderSAS » et « rootFolder » la réponse de l’API de charge utile du manifeste. Utilisez le kit sdk/outil Stockage Azure pour télécharger et décompresser le fichier blob. Il est au format de lignes JSON .
En-têtes de demande d’API standard
Toutes les API acceptent les en-têtes suivants :
| Nom | Obligatoire | Type | Description |
|---|---|---|---|
| Autorisation | True | Chaîne | Jeton du porteur d’autorisation. |
| ms-correlationid | False | Chaîne | Suivi de demande interne. Chaque requête génère un nouveau suivi (GUID). |
| ms-cv | False | Chaîne | Suivi de demande interne. |
| ms-requestid | False | Chaîne | ID d’idempotency de la requête. |
États de réponse de l’API standard
Voici les états HTTP de la réponse de l’API :
| Nom | Description |
|---|---|
| 400 Demande incorrecte | Il y avait des données manquantes ou incorrectes. Les détails de l’erreur sont inclus dans le corps de la réponse. |
| 401 Non autorisé | L’appelant n’est pas authentifié et doit s’authentifier auprès du service d’API partenaire avant d’effectuer le premier appel. |
| 403 Interdit | L’appelant n’est pas autorisé à effectuer la demande. |
| 500 Erreur interne du serveur | L’API ou l’une de ses dépendances ne peut pas répondre à la demande. Réessayez plus tard. |
| 404 Not Found | Ressource non disponible avec les paramètres d’entrée. |
| 410 Supprimé | Le lien manifeste a expiré ou expiré. Envoyez une nouvelle demande. |
Attributs de données d’utilisation
La réponse de l’API d’utilisation facturée ou non facturée avec le paramètre de requête « full » ou « basic » retourne les attributs suivants :
| Attribut | « full » | « de base » |
|---|---|---|
| PartnerId | Oui | Oui |
| PartnerName | Oui | Oui |
| CustomerId | Oui | Oui |
| CustomerName | Oui | Oui |
| CustomerDomainName | Oui | non |
| CustomerCountry | Oui | non |
| MpnId | Oui | non |
| Tier2MpnId | Oui | non |
| InvoiceNumber | Oui | Oui |
| ProductId | Oui | Oui |
| SkuId | Oui | Oui |
| AvailabilityId | Oui | non |
| SkuName | Oui | Oui |
| ProductName | Oui | non |
| PublisherName | Oui | Oui |
| PublisherId | Oui | non |
| SubscriptionDescription | Oui | non |
| SubscriptionId | Oui | Oui |
| ChargeStartDate | Oui | Oui |
| ChargeEndDate | Oui | Oui |
| UsageDate | Oui | Oui |
| MeterType | Oui | non |
| MeterCategory | Oui | non |
| MeterId | Oui | non |
| MeterSubCategory | Oui | non |
| MeterName | Oui | non |
| MeterRegion | Oui | non |
| Unité | Oui | Oui |
| ResourceLocation | Oui | non |
| ConsumedService | Oui | non |
| ResourceGroup | Oui | non |
| ResourceURI | Oui | Oui |
| ChargeType | Oui | Oui |
| UnitPrice | Oui | Oui |
| Quantité | Oui | Oui |
| UnitType | Oui | non |
| BillingPreTaxTotal | Oui | Oui |
| BillingCurrency | Oui | Oui |
| PricingPreTaxTotal | Oui | Oui |
| PricingCurrency | Oui | Oui |
| ServiceInfo1 | Oui | non |
| ServiceInfo2 | Oui | non |
| Étiquettes | Oui | non |
| AdditionalInfo | Oui | non |
| EffectiveUnitPrice | Oui | Oui |
| PCToBCExchangeRate | Oui | Oui |
| EntitlementId | Oui | Oui |
| EntitlementDescription | Oui | non |
| PartnerEarnedCreditPercentage | Oui | non |
| CreditPercentage | Oui | Oui |
| CreditType | Oui | Oui |
| BenefitOrderID | Oui | Oui |
| BenefitID | Oui | non |
| BenefitType | Oui | Oui |