103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
# MetaApi - Meta Marketing API Provider Service
|
|
|
|
Standalone microservice for Meta (Facebook/Instagram) advertising integration. Mirrors the GoogleApi architecture pattern — the Gateway routes `provider="meta"` requests here via internal HTTP.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Gateway ──(POST /internal/execute)──► MetaApi ──(Graph API)──► Meta Marketing API
|
|
X-Internal-Key auth │
|
|
├── Emulated mode (default)
|
|
└── Real API mode (Meta__EnableRealApi=true)
|
|
```
|
|
|
|
## Key Differences from GoogleApi
|
|
|
|
| Aspect | GoogleApi | MetaApi |
|
|
|--------|-----------|---------|
|
|
| Auth | OAuth refresh tokens | System User token (no expiry) |
|
|
| SDK | Google.Ads.GoogleAds NuGet | HttpClient → graph.facebook.com |
|
|
| Account format | Numeric customer ID | `act_XXXXXXXXXXXXXXX` |
|
|
| Hierarchy | Campaign → Ad Group → Ad | Campaign → Ad Set → Ad |
|
|
| API versioning | SDK version | URL path (`/v21.0/`) |
|
|
|
|
## Operations
|
|
|
|
| Operation | Description | Real API |
|
|
|-----------|-------------|----------|
|
|
| Ping / TestPing | Health check | N/A |
|
|
| CreateCampaign | Create Meta campaign | ✅ |
|
|
| GetCampaign | Retrieve campaign details | ✅ |
|
|
| UpdateCampaign | Update name/status/budget | ✅ |
|
|
| ListCampaigns | List campaigns with filters | ✅ |
|
|
| GetCampaignInsights | Campaign performance metrics | Emulated only |
|
|
| GetAccountInsights | Account-level metrics | Emulated only |
|
|
| CreateAdAccount | Create ad account under BM | ✅ |
|
|
| ListAdAccounts | List BM-owned ad accounts | ✅ |
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `META_INTERNAL_KEY` | Yes | Gateway→MetaApi shared auth key |
|
|
| `Meta__EnableRealApi` | No | `false` (default) = emulated responses |
|
|
| `Meta__AppId` | For real API | Meta App ID from Developer Portal |
|
|
| `Meta__AppSecret` | For real API | Meta App Secret |
|
|
| `Meta__SystemUserToken` | For real API | System User token from Business Manager |
|
|
| `Meta__BusinessManagerId` | For real API | USIM's Business Manager numeric ID |
|
|
| `Meta__ApiVersion` | No | Graph API version (default: `v21.0`) |
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
dotnet run --project MetaApi
|
|
# → http://localhost:5300
|
|
# → Swagger: http://localhost:5300/swagger
|
|
```
|
|
|
|
## Deploy to Azure Container Apps
|
|
|
|
```bash
|
|
az containerapp create \
|
|
--name usim-adp-metaapi \
|
|
--resource-group USIM-AdPlatform \
|
|
--environment usim-adp-env \
|
|
--image <registry>/usim-adp-metaapi:latest \
|
|
--target-port 5300 \
|
|
--ingress internal \
|
|
--env-vars \
|
|
META_INTERNAL_KEY=secretref:meta-internal-key \
|
|
Meta__EnableRealApi=false
|
|
```
|
|
|
|
## Gateway Integration
|
|
|
|
Add to Gateway environment:
|
|
```
|
|
META_PROVIDER_URL=https://usim-adp-metaapi.internal.<env>.azurecontainerapps.io
|
|
META_INTERNAL_KEY=<matching-key>
|
|
```
|
|
|
|
Gateway's `ExecutionService.GetProviderUrl()` already routes `provider="meta"` to `META_PROVIDER_URL`.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
MetaApi/
|
|
├── Configuration/
|
|
│ └── MetaConfig.cs # Config + MetaApiContext
|
|
├── Controllers/
|
|
│ └── InternalController.cs # /internal/execute + /internal/health
|
|
├── Models/
|
|
│ ├── OperationPayloads.cs # Meta-specific request payloads + enums
|
|
│ └── ProviderModels.cs # ProviderRequest/Response (Gateway contract)
|
|
├── Security/
|
|
│ └── InternalAuthFilter.cs # X-Internal-Key validation
|
|
├── Services/
|
|
│ ├── MetaGraphClient.cs # HTTP wrapper for graph.facebook.com
|
|
│ └── MetaMarketingService.cs # Operation dispatcher (emulated/real)
|
|
├── Program.cs
|
|
├── appsettings.json
|
|
└── MetaApi.csproj
|
|
```
|