Skip to content

Commit 09610bb

Browse files
xinyuwen2xinyuwen2
committed
update README.md
1 parent bc3fe9e commit 09610bb

1 file changed

Lines changed: 160 additions & 57 deletions

File tree

‎README.md‎

Lines changed: 160 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,179 @@
1-
# BingAdsApiSDK PHP REST OpenAPI Generator
1+
# msads-rest
22

3-
This project provides a PHP SDK for the Microsoft Bing Ads API, generated from OpenAPI specifications. It enables developers to interact with Bing Ads services using RESTful APIs in a modern, type-safe, and convenient way.
3+
This project provides the PHP client library for the REST-based Bing Ads API at Microsoft.
44

5-
## Features
5+
For documentation visit the [Bing Ads API Getting Started Page](https://learn.microsoft.com/en-us/advertising/guides/get-started).
66

7-
- **Auto-generated PHP client** for Bing Ads REST APIs using OpenAPI specs.
8-
- Generator Installation: [OpenAPI Generator CLI](https://openapi-generator.tech/docs/installation)
9-
- Currently available Bing Ads services:
10-
- CustomerManagementService
11-
- CustomerBillingService
12-
- CampaignManagementService
13-
- BulkService
14-
- ReportingService
15-
- Includes authentication helpers for OAuth2 flows.
16-
- PSR-compliant, compatible with modern PHP frameworks.
17-
- Unit tests and example usage included.
7+
## Installation & Usage
188

19-
## Project Structure
9+
### Requirements
2010

11+
PHP 7.4 and later.
12+
Should also work with PHP 8.0.
13+
14+
### Composer
15+
16+
To install the bindings via [Composer](https://getcomposer.org/), run the following command:
17+
18+
```bash
19+
composer require microsoft/msads
2120
```
22-
php_rest_openapi_gen/
23-
├── OpenApiSpecs/ # OpenAPI JSON specs for each Bing Ads service
24-
├── php_templates/ # Mustache templates used for code generation
25-
├── php-rest/ # Generated PHP SDK (src/api, src/model, etc.)
26-
│ ├── src/ # SDK source code
27-
│ │ ├── Api/ # API client classes for each service
28-
│ │ ├── Auth/ # Authentication classes (OAuth2)
29-
│ │ ├── Model/ # Data models for requests/responses and other entities
30-
│ │ ├── Configuration.php # API configuration and setup
31-
│ │ └── ObjectSerializer.php # Serializer for API requests/responses
32-
│ ├── test/ # Unit test and sample code
33-
│ ├── LICENSE.md # License file
34-
│ ├── composer.json # Composer configuration
35-
│ ├── composer.lock # Composer lock file
36-
│ ├── phpunit.xml # PHPUnit configuration
37-
│ └── README.md # SDK usage documentation
38-
├── openapitools.json # OpenAPI Generator config
39-
├── php-config.yaml # PHP codegen config specific to php generator
40-
├── generate-all.ps1 # PowerShell script to generate sdks for all specs in a folder
41-
└── README.md # This file
21+
22+
Then run `composer install`
23+
24+
### Manual Installation
25+
26+
Download the files and include `autoload.php`:
27+
28+
```php
29+
<?php
30+
require_once('/path/to/msads-rest/vendor/autoload.php');
4231
```
4332

44-
## Code Generation
33+
## Getting Started
34+
35+
Please follow the [installation procedure](#installation--usage) and then run the following:
36+
37+
```php
38+
<?php
39+
require_once(__DIR__ . '/vendor/autoload.php');
40+
41+
$config = \Microsoft\MsAds\Rest\Configuration::getDefaultConfiguration();
42+
43+
$authentication = (new \Microsoft\MsAds\Rest\Auth\OAuthDesktopMobileAuthCodeGrant())
44+
->withEnvironment(\Microsoft\MsAds\Rest\Auth\ApiEnvironment::SANDBOX)
45+
->withClientId(self::CLIENT_ID) // Replace with your client ID
46+
->withOAuthScope(\Microsoft\MsAds\Rest\Auth\OAuthScope::MSADS_MANAGE);
47+
48+
$config->setAuthorizationData((new \Microsoft\MsAds\Rest\Auth\AuthorizationData())
49+
->withAuthentication($authentication)
50+
->withDeveloperToken('BBD37VB98')); // For sandbox use 'BBD37VB98'
51+
52+
// To set the auth key manually
53+
// $config = $config->setApiKey('Authorization', 'YOUR_API_KEY');
54+
// $config = $config->setApiKey('UserName', 'YOUR_API_KEY');
55+
// $config = $config->setApiKey('CustomerAccountId', 'YOUR_API_KEY');
56+
// $config = $config->setApiKey('CustomerId', 'YOUR_API_KEY');
57+
// $config = $config->setApiKey('DeveloperToken', 'YOUR_API_KEY');
58+
// $config = $config->setApiKey('Password', 'YOUR_API_KEY');
59+
60+
61+
$apiInstance = new \Microsoft\MsAds\Rest\Api\CampaignManagementServiceApi(
62+
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
63+
// This is optional, `GuzzleHttp\Client` will be used as default.
64+
new \GuzzleHttp\Client(),
65+
$config,
66+
null,
67+
\Microsoft\MsAds\Rest\Auth\ApiEnvironment::SANDBOX
68+
);
69+
$request = new \Microsoft\MsAds\Rest\Model\CampaignManagementService\AddAdExtensionsRequest();
70+
$request->setAdExtensions([
71+
new \Microsoft\MsAds\Rest\Model\CampaignManagementService\ImageAdExtension([
72+
'Name' => 'Test Image Ad Extension',
73+
])
74+
]);
4575

46-
To regenerate the SDK from updated OpenAPI specs, select the right spec json and `modelPackage` name, for example:
76+
try {
77+
$result = $apiInstance->addAdExtensions($request);
78+
print_r($result);
79+
} catch (Exception $e) {
80+
echo 'Exception when calling CampaignManagementServiceApi->addAdExtensions: ', $e->getMessage(), PHP_EOL;
81+
}
4782

48-
```powershell
49-
openapi-generator-cli generate -g php -o .\php-rest `
50-
-i .\OpenApiSpecs\CustomerBillingService.json `
51-
-c .\php-config.yaml `
52-
-p modelPackage="Model\CustomerBillingService" `
53-
--global-property="models,apis,supportingFiles,apiDocs=false,modelDocs=false,apiTests=false,modelTests=false";
5483
```
5584

56-
Repeat for each service spec as needed.
85+
## Handling Responses and Exceptions
86+
- The API uses standard HTTP response codes to indicate the success or failure of an API request. In general, `2xx` codes indicate success, while `4xx` and `5xx` codes indicate errors.
87+
- In certain cases, the API will return an `ApplicationFault` response with an error message and an error code. The error message will provide more details about the error.
88+
- If there is an error with the API call itself, the SDK will throw an `ApiException` with the error message and code. You can catch this exception and handle it accordingly.
5789

58-
Or, you can use the provided powershell script to generate **all services** at once:
90+
Example of handling responses:
91+
```php
92+
try {
93+
$response = $apiInstance->addAdExtensions($AddAdExtensionsRequest);
94+
if ($response instanceof ApplicationFault) {
95+
echo 'Handle the ApplicationFault response here';
96+
} else {
97+
echo 'Handle the AddAdExtensionsResponse response here';
98+
}
99+
} catch (ApiException $e) {
100+
echo 'Exception when calling AdExtensionService->addAdExtensions: ', $e->getMessage(), PHP_EOL;
101+
}
102+
```
103+
104+
## Flag Enums
105+
The SDK uses `Flag Enums` to represent various options and settings.
106+
- These `Flag Enums` allow you to combine multiple options. For example, you can use the `CampaignManagementService\AdExtensionsTypeFilter` enum to specify multiple AdExtensionTypeFilters using an array of values OR comma-separated string.
107+
- To check if an Enum class is a `Flag Enum`, you can look for the `$isFlags` property in the class definition. If it is set to `true`, you can use the enum as a `Flag Enum`.
108+
- When a `Flag Enum` is returned from the API in deserialization, it will be represented as a string with the values separated by commas.
59109

60-
```powershell
61-
.\generate-all.ps1 # uses default paths below, or you can specify custom paths
62-
# .\generate-all.ps1 -specsFolder "./OpenApiSpecs" -outputFolder "./php-rest" -configFile "./php-config.yaml"
110+
```php
111+
use \Microsoft\MsAds\Rest\Model\CampaignManagementService\AdExtensionsTypeFilter;
112+
// To represent multiple AdExtensionTypeFilters:
113+
$filter = [AdExtensionsTypeFilter::ACTION_AD_EXTENSION, AdExtensionsTypeFilter::APP_AD_EXTENSION];
114+
// or
115+
$filter = 'ActionAdExtension,AppAdExtension';
116+
// or
117+
$filter = AdExtensionsTypeFilter::ACTION_AD_EXTENSION . ',' . AdExtensionsTypeFilter::APP_AD_EXTENSION;
118+
// or
119+
$filter = new AdExtensionsTypeFilter($filter);
63120
```
64121

65-
## Resources
66-
- [Bing Ads API Documentation](https://learn.microsoft.com/en-us/advertising/guides/)
67-
- OpenAPI Generator Documentation:
68-
- [CLI Installation](https://openapi-generator.tech/docs/installation)
69-
- [Using Templates](https://openapi-generator.tech/docs/templating)
70-
- [Customizing Code Generation](https://openapi-generator.tech/docs/customization)
71-
- [Configuration Options](https://openapi-generator.tech/docs/generators/php#configuration-options)
122+
## Authorization
123+
You can use the OAuth 2.0 authorization flow to obtain the necessary tokens for accessing the Bing Ads API. The SDK supports both web-based and desktop-based OAuth flows.
124+
You can find more information on how to obtain these tokens in the [Bing Ads API documentation](https://learn.microsoft.com/en-us/advertising/guides/authentication-oauth).
125+
- Classes are provided in the SDK to help you with the OAuth 2.0 flow, within the folder [src/Auth](src/Auth).
126+
- Sample code can be found in the `test` directory, specifically in the [test/WebAuthentication](test/WebAuthentication) directory for webpage auth, and [test/RestApiTestBase.php](test/RestApiTestBase.php) for OAuth Desktop auth.
127+
128+
Authentication schemes defined for the API:
129+
### Authorization
130+
- **Type**: API key
131+
- **API key parameter name**: Authorization
132+
- **Location**: HTTP header
133+
134+
### UserName
135+
- **Type**: API key
136+
- **API key parameter name**: UserName
137+
- **Location**: HTTP header
138+
139+
### Password
140+
- **Type**: API key
141+
- **API key parameter name**: Password
142+
- **Location**: HTTP header
143+
144+
### CustomerAccountId
145+
- **Type**: API key
146+
- **API key parameter name**: CustomerAccountId
147+
- **Location**: HTTP header
148+
149+
### CustomerId
150+
- **Type**: API key
151+
- **API key parameter name**: CustomerId
152+
- **Location**: HTTP header
153+
154+
### DeveloperToken
155+
- **Type**: API key
156+
- **API key parameter name**: DeveloperToken
157+
- **Location**: HTTP header
158+
159+
## Samples and Tests
160+
161+
There are some samples included in the [test](test) directory showing examples of how to use the SDK.
162+
163+
The samples are written using PHPUnit. To run the tests, you need to have PHPUnit installed. You can install it globally or use Composer to install it as a dependency.
164+
165+
> **Warning**: Before running the tests, make sure to set up your environment variables for the API keys. You can do this by editing the CONSTANTS in the [RestApiTestBase.php](test/RestApiTestBase.php) file, going through the auth flow to get the `CODE_URL` and then replacing that constant.
166+
167+
To run the tests, use an IDE or run the following command in the terminal:
168+
169+
```bash
170+
composer install
171+
vendor/bin/phpunit
172+
```
72173

73-
---
174+
Logs will be generated in the base directory of the project with the request and response data for further analysis.
74175

75-
*Generated with OpenAPI Generator and custom templates.*
176+
## About this package
76177

178+
- SDK Package version: `13.0.26`
179+
- Generated date: `2025-12-11T13:28:36.717081200+08:00[Asia/Shanghai]`

0 commit comments

Comments
 (0)