API de rapprochement d’utilisation facturée et non facturée par jour v2 (GA)

Article
09/25/2024

S’applique à : Espace partenaires (indisponible dans Azure Government ou Azure China 21Vianet.)

Nos API asynchrones offrent un moyen plus rapide et plus gérable d’accéder aux données de facturation et de rapprochement par le biais d’objets blob Azure. Avec ces API, vous n’avez pas besoin de conserver la connexion ouverte pendant des heures ou de parcourir les lots de 2 000 éléments de ligne.

Nous avons optimisé nos nouvelles API de rapprochement d’utilisation quotidiennes commerciales à l’aide de la clé de valet et des modèles de demande-réponse asynchrones. Lorsque vous utilisez ces API, vous recevez un jeton que vous pouvez utiliser pour accéder à tous les attributs ou à un sous-ensemble des données de rapprochement d’utilisation évaluées quotidiennement.

Remarque

Les nouvelles API ne sont pas hébergées sur l’hôte de l’API de l’Espace partenaires. Au lieu de cela, vous pouvez les trouver sur MS Graph à l’aide de l’API Microsoft Graph pour exporter les données de facturation des partenaires - Microsoft Graph v1.0 | Microsoft Learn. Pour accéder à ces API, reportez-vous aux détails suivants.

Vous ne pouvez utiliser ces API pour le cloud public/mondial MS Graph que maintenant. Ils ne sont pas encore disponibles pour Azure Government ou Azure China 21Vianet.

Important

Pour accorder à votre application l’autorisation nécessaire pour accéder aux données de facturation des partenaires, vous devez suivre ce lien et en savoir plus sur les principes de base de l’authentification et de l’autorisation pour Microsoft Graph.

En règle générale, vous pouvez utiliser Portail Azure ou entra Admin Center pour attribuer l’autorisation requise : « PartnerBilling.Read.All ». Voici les étapes à suivre :

Inscrivez votre application sur la page d’accueil de Microsoft Entra sous la section Inscriptions d’applications.
Attribuez l’autorisation à votre application dans la page Microsoft Entra App sous la section Autorisations de l’API. Sélectionnez « Ajouter une autorisation » et choisissez l’étendue « PartnerBilling.Read.All ».

Remarque

Si vous utilisez notre version bêta, vous ne remarquerez peut-être pas de modifications significatives dans la version en disponibilité générale. Nous vous recommandons de comparer les deux versions pour comprendre les différences et les mises à jour.

Important

La nouvelle utilisation quotidienne du commerce n’inclut 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

Pour récupérer de nouveaux éléments de ligne d’utilisation quotidiens du commerce de manière asynchrone, utilisez deux points de terminaison d’API. Le processus est le suivant :

Point de terminaison de ligne d’utilisation

Utilisez cette API pour récupérer les éléments de ligne d’utilisation facturés ou non facturés par jour. Vous obtenez un état HTTP 202 et une URL dans l’en-tête d’emplacement. Interrogez cette URL à 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

Pour obtenir un état de réussite, continuez à appeler cette API à intervalles réguliers. Si les données ne sont pas prêtes, la réponse de l’API inclut un en-tête Retry-After pour vous indiquer le délai d’attente avant de réessayer. Une fois l’opération terminée, vous obtenez une ressource de manifeste avec un dossier de stockage dans lequel vous pouvez télécharger les données d’utilisation. La réponse décompose les fichiers en morceaux plus petits pour un débit optimisé et un parallélisme d’E/S optimisés.

Diagramme de séquence

Voici un diagramme de séquence qui montre les étapes de téléchargement des données de rapprochement.

Diagramme montrant les étapes de téléchargement de la rapprochement.

Séquence d’actions utilisateur

Pour récupérer les nouveaux éléments de ligne de rapprochement d’utilisation évalués quotidiennement par le commerce , procédez comme suit :

É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 tous les jours

Obtenez de nouveaux éléments de ligne d’utilisation quotidiens non facturés pour le mois ou le dernier mois calendrier ou la période 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.

Requête d’API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

Corps de la demande

Attribut	Obligatoire	Type	Description
attributeSet	False	Chaîne	Choisissez « full » pour tous les attributs ou « de base » pour un ensemble limité. La valeur par défaut est « full ». (Consultez la liste des attributs ici). facultatif.
billingPeriod	True	Chaîne	Utilisez « actuel » ou « dernier » (identique à « précédent » dans les API V1) pour obtenir l’utilisation quotidienne évaluée pour le mois actuel ou le dernier mois calendrier ou la période de facturation. Obligatoire.
currencyCode	True	Chaîne	Code monétaire de facturation du partenaire. Obligatoire.

En-têtes de requête

Pour demander des en-têtes pour l’API, consultez Fiabilité et prise en charge.

Réponse de l’API

HTTP/1.1 202 Accepted  
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Lorsque vous utilisez l’API, elle retourne généralement un état HTTP 202. Pour afficher d’autres états possibles en fonction de vos demandes, consultez les états de réponse de l’API Standard.

Code	Description
202 – Accepté	Votre demande a été acceptée. Pour vérifier l’état de votre demande, interrogez l’URL fournie dans l’en-tête d’emplacement.

Obtenir les éléments de ligne d’utilisation facturés tous les jours

Obtenez les nouveaux éléments de ligne d’utilisation facturés quotidiennement pour une facture pour la période de facturation fermée.

Requête d’API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Paramètres de requête

S/O

Corps de la demande

Attribut	Obligatoire	Type	Description
invoiceId	True	Chaîne	Identificateur unique pour chaque facture. Obligatoire.
attributeSet	False	Chaîne	Choisissez « full » pour tous les attributs ou « de base » pour un ensemble limité. La valeur par défaut est « full ». (Consultez la liste des attributs ici). facultatif.

En-tête de requête

En-têtes de requête pour l’API. Pour en savoir plus, consultez la fiabilité et la prise en charge.

Réponse de l’API

HTTP/1.1 202 Accepté
Emplacement : https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Lorsque vous utilisez l’API, elle retourne généralement un état HTTP 202. Pour obtenir d’autres états possibles en fonction de vos demandes, consultez Statuses.

Code	Description
202 – Accepté	Votre demande a été acceptée. Pour vérifier l’état de votre demande, interrogez l’URL fournie dans l’en-tête d’emplacement.

Étape 2 : Vérifier l’état de la demande

Pour vérifier l’état d’une requête, attendez une réponse HTTP 200 avec l’état « réussi » ou « échec ». Si la requête réussit, l’URL du manifeste est fournie dans l’attribut « resourceLocation ».

Obtenir l’état de l’opération

Récupère l’état d’une demande.

Requête d’API

GET https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Paramètres de la demande

Nom	Inclure dans	Requis	Type	Description
operationId	URI de demande	True	Chaîne	ID unique pour vérifier l’état de la demande. Obligatoire.

En-tête de requête

Pour demander des en-têtes pour l’API, consultez Fiabilité et prise en charge.

Corps de la demande

N/A.

État de la réponse

Outre les états HTTP standard, l’API peut retourner l’état HTTP suivant :

Code	Description
410 - Disparu	Le lien manifeste est actif uniquement pendant une durée spécifique définie par le serveur. Une fois ce délai écoulé, vous devez envoyer une nouvelle demande d’accès au manifeste.

Charge utile de réponse

La charge utile de réponse de l’API inclut les attributs suivants :

Attribut	Obligatoire	Description
id	True	ID unique pour chaque réponse. Obligatoire.
statut	True	Valeurs et actions (obligatoires) : notstarted : attendez l’heure spécifiée dans l’en-tête « Réessayer-After », puis effectuez un autre appel pour vérifier l’état. en cours d’exécution : attendez l’heure spécifiée dans l’en-tête « Réessayer-After », puis effectuez un autre appel pour vérifier l’état. réussite : les données sont prêtes. Récupérez la charge utile du manifeste à l’aide de l’URI spécifié dans resourceLocation. échec : l’opération a échoué définitivement. Redémarrez-le.
createdDateTime	True	Heure à laquelle la demande a été faite. Obligatoire.
lastActionDateTime	True	Heure de la dernière modification de l’état. Obligatoire.
resourceLocation	False	URI de la charge utile du manifeste. facultatif.
error	False	Si l’opération échoue, les détails de l’erreur sont fournis au format JSON. facultatif. Les attributs suivants peuvent être inclus : message (obligatoire) : description détaillée de l’erreur. code (obligatoire) : type d’erreur qui s’est produite.

Objet Resource Location

Attribut	Description
id	Identificateur unique du manifeste.
schemaVersion	Version du schéma de manifeste.
dataFormat	Format du fichier de données de facturation. compresséJSON : format de données où chaque objet blob est un fichier compressé qui contient des données au format de lignes JSON . Pour récupérer les données de chaque objet blob, décompressez-les.
createdDateTime	Date et 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.
partnerTenantId	ID du locataire du partenaire.
rootDirectory	Répertoire racine du fichier.
sasToken	Jeton SAP (signature d’accès partagé) qui vous permet de lire tous les fichiers sous le répertoire.
partitionType	Divise les données en plusieurs objets blob en fonction de l’attribut « partitionValue ». Le système fractionne les partitions qui dépassent le nombre pris en charge. Par défaut, les données sont partitionnée 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 le code, car ces valeurs peuvent changer.
blobCount	Nombre total de fichiers pour cet ID de locataire partenaire.
blobs	Tableau JSON d’objets « blob » qui contiennent les détails du fichier pour l’ID de locataire partenaire.
objet blob	Objet qui contient les détails suivants :
name	Le nom de l’objet Blob.
partitionValue	Partition qui contient le fichier. La grande partition est divisée en plusieurs fichiers, chaque fichier contenant le même « partitionValue ».

Requête d’API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Réponse de l’API

La réponse recommande d’attendre 10 secondes avant de réessayer lors du traitement des données.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"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://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Réponse de l’API

L’API retourne l’état « réussi » et l’URI de « resourceLocation ».

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "0e195b37-4574-4539-bc42-0e539b9684c0",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Étape 3 : Télécharger les éléments de ligne de rapprochement d’utilisation évalués quotidiennement à partir du stockage Blob Azure

Obtenez le jeton de signature d’accès partagé (SAP) et l’emplacement de stockage d’objets blob à partir des propriétés « sasToken » et « rootDirectory » 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 JSONLines .

Conseil

Consultez notre exemple de code pour télécharger et décompresser le fichier blob Azure dans votre base de données locale.

États de réponse de l’API standard

Vous pouvez recevoir ces états HTTP à partir de la réponse de l’API :

Code	Description
400 Demande incorrecte.	La demande est manquante ou contient des données incorrectes. Recherchez les détails de l’erreur dans le corps de la réponse.
401 - Non autorisé	L’appelant n’est pas authentifié et vous devez vous authentifier auprès du service d’API partenaire avant d’effectuer le premier appel.
403 - Interdit	Vous n’avez pas l’autorisation nécessaire pour effectuer la demande.
404 - Non trouvé	Les ressources demandées ne sont pas disponibles avec les paramètres d’entrée fournis.
410 - Disparu	Le lien manifeste a expiré ou expiré. Envoyez une nouvelle demande.
500 - Erreur interne du serveur	L’API ou l’une de ses dépendances ne peut pas répondre à la demande pour l’instant. Réessayez plus tard.
5000 – Aucune donnée disponible	Le système n’a pas de données pour les paramètres d’entrée fournis.

Comparer les versions bêta et ga

Consultez le tableau de comparaison pour comprendre les différences entre les versions bêta et en disponibilité générale. Si vous utilisez la version bêta, le passage à la version ga doit être simple.

Informations importantes	Bêta	Disponibilité générale
Point de terminaison de l’hôte d’API	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
Méthode HTTP	POST	POST
Point de terminaison de l’API d’utilisation quotidienne non facturé	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Paramètres d’entrée pour l’API d’utilisation quotidienne non facturée	Pour spécifier des paramètres dans la requête d’API, incluez-les dans la chaîne de requête de l’URL de la requête. Par exemple, pour spécifier les paramètres period et currencyCode, ajoutez `?period=current&currencyCode=usd` à l’URL de la requête.	Pour fournir des entrées, incluez un objet JSON dans le corps de la requête. L’objet JSON doit contenir les propriétés suivantes : * currencyCode : code monétaire de la facture. Par exemple, USD. * billingPeriod : période de facturation de la facture. Par exemple, en cours. Voici un exemple d’objet JSON qui inclut les propriétés currencyCode et billingPeriod :`<br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>}`
Point de terminaison de l’API d’utilisation facturé par jour	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId}`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
Paramètres d’entrée pour l’API d’utilisation quotidienne facturée	Pour spécifier des paramètres dans la requête d’API, incluez l’ID de facture dans l’URL de la requête. En outre, vous pouvez inclure un paramètre de fragment facultatif dans la chaîne de requête pour récupérer l’ensemble complet d’attributs. Par exemple, pour récupérer l’ensemble complet d’attributs, ajoutez `?fragment=full` à l’URL de la requête.	Pour fournir des entrées, incluez un objet JSON dans le corps de la requête. L’objet JSON doit contenir les propriétés suivantes : * invoiceId : ID de la facture. Par exemple, G00012345. * attributeSet : ensemble d’attributs à inclure dans la réponse. Par exemple, complète. Voici un exemple d’objet JSON qui inclut les propriétés invoiceId et attributeSet : `{<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}`
Ressource de manifeste	Utilisez une méthode GET /manifests/{id} distincte pour récupérer la ressource de manifeste.	Utilisez la méthode GET /operations/{Id}, qui retourne la ressource de manifeste associée dans resourceLocation, ce qui élimine la nécessité d’un appel distinct à la méthode GET /manifests/{id}.
Modifications apportées au schéma de manifeste
	« id » : Non disponible	« id » : identificateur unique de la ressource de manifeste.
	« version » : Disponible	« version » : renommé en « schemaversion ».
	« dataFormat » : disponible	« dataFormat » : disponible.
	« utcCretedDateTime » : Disponible	« utcCretedDateTime » : renommé en « createdDateTime ».
	« eTag » : Disponible	« eTag » : disponible.
	« partnerTenantId » : Disponible	« partnerTenantId » : Disponible
	« rootFolder » : disponible	« rootFolder » : renommé en « rootDirectory ».
	« rootFolderSAS » : disponible	« rootFolderSAS » : renommé en « sasToken ». Il fournit désormais un jeton et n’inclut plus le chemin du répertoire racine. Pour accéder au répertoire, utilisez plutôt la propriété « rootDirectory ».
	« partitionType » : Disponible	« partitionType » : disponible.
	« blobCount » : disponible	« blobCount » : disponible.
	« sizeInBytes » : Disponible	« sizeInBytes » : non disponible.
	« objets blob » : disponible	« objets blob » : disponible.
	« objet blob » : disponible	« objet blob » : disponible.
	« name » : Disponible	« name » : Disponible.
	« partitionValue » : Disponible	« partitionValue » : disponible.

Attributs quotidiens de l’élément de ligne de rapprochement de l’utilisation

Pour comparer les attributs retournés par l’API de rapprochement d’utilisation évaluée quotidiennement pour les ensembles d’attributs « complets » ou « de base », reportez-vous aux informations suivantes. Pour en savoir plus sur ces attributs, consultez cette documentation.

Attribut	COMPLET	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

Important

Notez ces modifications lors du passage à l’API v2 à partir de la version 1.

Le nom de chaque attribut commence en majuscules.
unitOfMeasure est maintenant Unit. La signification et la valeur de l’attribut sont identiques.
resellerMpnId est maintenant Tier2MpnId. La signification et la valeur de l’attribut sont identiques.
Le nom et la valeur de rateOfPartnerEarnedCredit ont changé en PartnerEarnedCreditPercentage. Le nouveau nom et la nouvelle valeur de l’attribut reflètent le pourcentage au lieu de la fraction. Par exemple, 0.15 est maintenant 15.
rateOfCredit est maintenant CreditPercentage. La signification et la valeur de l’attribut ont changé. Par exemple, la version 1.00 est maintenant 100.

Exemple de code

Pour plus d’informations, consultez les exemples d’API de l’Espace partenaires : Obtenir des données de reconquête de facturation.

Partager via

API de rapprochement d’utilisation facturée et non facturée par jour v2 (GA)

Présentation de l’API

Point de terminaison de ligne d’utilisation

Point de terminaison d’état de l’opération

Diagramme de séquence

Séquence d’actions utilisateur

Étape 1 : Envoyer une demande

Obtenir des éléments de ligne d’utilisation non facturés tous les jours

Requête d’API

Corps de la demande

En-têtes de requête

Réponse de l’API

Obtenir les éléments de ligne d’utilisation facturés tous les jours

Requête d’API

Corps de la demande

En-tête de requête

Réponse de l’API

Étape 2 : Vérifier l’état de la demande

Obtenir l’état de l’opération

Requête d’API

Paramètres de la demande

En-tête de requête

Corps de la demande

État de la réponse

Charge utile de réponse

Objet Resource Location

Requête d’API

Réponse de l’API

Requête d’API

Réponse de l’API

Étape 3 : Télécharger les éléments de ligne de rapprochement d’utilisation évalués quotidiennement à partir du stockage Blob Azure

États de réponse de l’API standard

Comparer les versions bêta et ga

Attributs quotidiens de l’élément de ligne de rapprochement de l’utilisation

Exemple de code

Commentaires

Ressources supplémentaires