Partage via


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.

Diagramme montrant 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