API de facturation et de rapprochement v2 (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 des données d’utilisation facturées et non facturées quotidiennement de manière asynchrone.
Remarque
Cette API pour l’utilisation facturée quotidienne cessera de fonctionner après le 30 juin 2024. Reportez-vous aux informations suivantes pour décider de la version à utiliser et à quel moment.
- Sauf si vous avez basculé vers la version ga v2, utilisez cette API jusqu’au 30 juin 2024 pour obtenir les éléments de ligne d’utilisation facturés tous les jours pour les factures créées pour les périodes de facturation comprises entre septembre 2022 et juin 2024.
- Utilisez uniquement l’API v2 GA après le 30 juin 2024 pour obtenir les éléments de ligne d’utilisation facturés tous les jours pour les factures créées pour les périodes de facturation de septembre 2022.
Cette API pour l’utilisation quotidienne non facturée cesse de fonctionner après le 30 juin 2024. Reportez-vous aux informations suivantes pour décider de la version à utiliser et à quel moment.
- À moins que vous n’ayez basculé vers la disponibilité générale v2, utilisez cette API jusqu’au 30 juin 2024 pour obtenir des éléments de ligne d’utilisation évalués tous les jours non facturés pour les périodes de facturation actuelles et précédentes.
- Utilisez uniquement l’API v2 GA après le 30 juin 2024 afin d’obtenir des éléments de ligne de l’utilisation quotidienne non facturée pour la facturation actuelle et antérieure.
Pour commencer à préparer la migration vers les nouvelles API de disponibilité générale v2, consultez le lien suivant :
API de rapprochement d’utilisation facturée et non facturée par jour v2 (GA)
Remarque
Vous pouvez récupérer vos données d’utilisation quotidiennes non facturées via l’API ou le portail de l’Espace partenaires. La disponibilité des données peut prendre jusqu’à 24 heures. Toutefois, il peut y avoir d’autres retards en fonction de votre emplacement et lorsque les compteurs signalent l’utilisation.
Parfois, vous ne voyez peut-être pas les données d’utilisation non facturées les plus récentes tant que les données d’utilisation facturées pour le mois précédent ne sont pas remises. Cela permet de s’assurer que les données d’utilisation facturées sont fournies dans le délai convenu. Une fois que vous avez reçu les données d’utilisation facturées, vous devez être en mesure de récupérer toutes les données d’utilisation non facturées mises à jour à partir du début du mois.
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 tiers
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 avons utilisé les modèles de clé de valet et de demande-réponse 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 plus d’informations, consultez les articles suivants :
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. Il 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 ci-dessous illustre les étapes nécessaires pour télécharger les données de rapprochement.
Séquence d’actions utilisateur
Suivez les étapes ci-dessous 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.) |
| Size | N/A. |
| Décalage | 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 a été 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.) |
| Size | N/A. |
| Décalage | 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 a été 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 sera « 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 l’état HTTP ci-dessous :
| 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 case activée l’état après avoir attendu l’heure spécifiée dans l’en-tête « Réessayer-After ». |
| exécution en cours | Effectuez un autre appel pour case activée l’état après avoir attendu l’heure spécifiée dans l’en-tête « Réessayer-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 l’état HTTP ci-dessous :
| 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. Décompressez le fichier pour accéder aux données. |
| 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 ». Les données sont partitionnée par le nombre d’éléments de ligne dans le fichier par défaut. Ne définissez pas un nombre fixe d’éléments de ligne ou de taille de fichier dans votre code, car ils peuvent 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. Veuillez réessayer 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 |
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour