API de rapprochement d’utilisation facturée et non facturée par jour v2 (GA)
S’applique à : Espace partenaires (indisponible dans Azure Government, Azure Allemagne 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, Azure Allemagne ou Azure Chine 21Vianet.
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
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.
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.
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 case activée 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 case activée 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 case activée 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
Paramètres de la demande
| Nom | Inclure dans | Requis | Type | Description |
|---|---|---|---|---|
| operationId | URI de demande | True | Chaîne | ID unique pour case activée 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 case activée 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 case activée 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 – Introuvable | 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. |
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¤cyCode=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.
| 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.
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