Versi Graph API

Ad Label

API users tend to create 1000s of campaigns/ad sets/ads, and would like to have the ability to group together sets of ad objects arbitrarily. For example, an advertiser may want to track all campaigns that are targeting men or women, or track all ads that are using the same creative. Or use external data, like, track all campaigns that were created by a particular team, as a part of a particular marketing initiative.

Until now this could be achieved by overloading the name of the ad object. API developers have come up with complicated naming schemes, creating campaigns with names like “[client]-[fmp]-[autogen]-[18-34-oregon]-[custaudience-141]”, and these names are used to parse out tags.

With the introduction of Labels API, we allow developers to tag ad objects with multiple "labels" (strings). Developers can query by these labels, so they can quickly collate and query ad objects such as campaigns, ad sets, ads and creatives that belong to the same “label”.

Limits

The following are the limits on ad sets

Limit	Value
Maximum number of ad labels per regular ad account	100,000 non-deleted ad labels
Maximum number of ad labels specified in the spec (to be associated with an ad object)	50 ad labels spec

Membaca

An AdLabel

Examples

Getting all labels within the account:

Getting labels associated with a given ad object:

Getting ad objects associated with a given label

For an ad account, one can retrieve ad objects associated with an ad label. This can be achieved by:

for campaigns, using endpoint /campaignsbylabels
for ad sets, using endpoint /adsetsbylabels
for ads, using endpoint /adsbylabels
for creatives, using endpoint /adcreativesbylabels

Supported operators are ALL and ANY: for ids and label names matching, partial string matching is not supported.

curl -G \
  -d 'ad_label_ids=["<AD_LABEL_ID>"]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adsbylabels

Filtering by names using {object}.adlabels on Insights edge:

Filtering by ids using {object}.adlabel_ids on Insights edge:

Similarly, field filtering can be used for finding ads, ad sets, campaigns just as done on the insights edge:

The filtering parameter is an array of filter object. Each filter object has three fields: 'field', 'operator' and 'value'. Valid filter operator could be ('EQUAL', 'NOT_EQUAL', 'GREATER_THAN', 'GREATER_THAN_OR_EQUAL', 'LESS_THAN', 'LESS_THAN_OR_EQUAL', 'IN_RANGE', 'NOT_IN_RANGE', 'CONTAIN', 'NOT_CONTAIN', 'IN', 'NOT_IN', 'ANY', 'ALL', 'NONE').

Parameter

Titik akhir ini tidak memiliki parameter.

Kolom

Kolom	Keterangan
`id` numeric string	Ad Label ID
`created_time` datetime	Created time
`name` string	Ad Label name Default
`updated_time` datetime	Updated time

Tepi

Edge	Keterangan
`adcreatives` Edge<AdCreative>	Creatives associated with this label
`ads` Edge<Adgroup>	Ads associated with this label
`adsets` Edge<AdCampaign>	Ad sets associated with this label
`campaigns` Edge<AdCampaignGroup>	Campaigns associated with this label

Error Codes

Kesalahan	Description
100	Invalid parameter

Membuat

Examples

Creating Labels:

You can make a POST request to adlabels edge from the following paths:

/act_{ad_account_id}/adlabels

When posting to this edge, an AdLabel will be created.

Contoh

Graph API Explorer

POST /v24.0/act_<AD_ACCOUNT_ID>/adlabels HTTP/1.1
Host: graph.facebook.com

name=My+Label

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/adlabels',
    array (
      'name' => 'My Label',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/act_<AD_ACCOUNT_ID>/adlabels",
    "POST",
    {
        "name": "My Label"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Bundle params = new Bundle();
params.putString("name", "My Label");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/adlabels",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();

NSDictionary *params = @{
  @"name": @"My Label",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/adlabels"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

curl -X POST \
  -F 'name="My Label"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adlabels

Jika Anda ingin mempelajari cara menggunakan Graph API, baca Menggunakan panduan Graph API kami.

Parameter

Parameter Keterangan

Parameter	Keterangan
`name` string	AdLabel name Diperlukan

name

string

AdLabel name

Diperlukan

Jenis Pengembalian

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

Error Codes

Kesalahan	Description
100	Invalid parameter
200	Permissions error

Memperbarui

Examples

Renaming Labels: One can rename to a new name, only if a label with that name does not exist.

Associating with ad objects: One can use 'id' or 'name'. If a label with a given name exists, it will be re-used.

Associating an existing label with an existing ad object such as ads:

This endpoint overrides all set of labels associated with this object, whereas <OBJECT_ID>/adlabels modifies (adds new or reuses specified). If only the label name is supplied, and a label with the name does not exist, then a new label is created and then associated with the ad object.

Adding new associations to existing ad object such as ads using label id

You can update an AdLabel by making a POST request to /{ad_label_id}.

Parameter

Parameter Keterangan

Parameter	Keterangan
`name` string	AdLabel name Diperlukan

name

string

AdLabel name

Diperlukan

Jenis Pengembalian

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Error Codes

Kesalahan	Description
100	Invalid parameter

You can update an AdLabel by making a POST request to /{ad_creative_id}/adlabels.

Parameter

Parameter Keterangan

Parameter	Keterangan
`adlabels` list<Object>	Specification of ad labels to be associated with the creative Diperlukan

adlabels

list<Object>

Specification of ad labels to be associated with the creative

Diperlukan

Jenis Pengembalian

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Error Codes

Kesalahan	Description
100	Invalid parameter

You can update an AdLabel by making a POST request to /{ad_id}/adlabels.

Parameter

Parameter Keterangan

Parameter	Keterangan
`adlabels` list<Object>	Specification of adlabels to be associated with the ad Diperlukan
`execution_options` list<enum{validate_only}>	Nilai default: `Set` An execution setting `validate_only`: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field. If the call passes validation or review, response will be `{"success": true}`. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

adlabels

list<Object>

Specification of adlabels to be associated with the ad

Diperlukan

execution_options

list<enum{validate_only}>

Nilai default: Set

An execution setting
validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

Jenis Pengembalian

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Error Codes

Kesalahan	Description
100	Invalid parameter

You can update an AdLabel by making a POST request to /{campaign_id}/adlabels.

Parameter

Parameter Keterangan

Parameter	Keterangan
`adlabels` list<Object>	Specification of ad labels to be associated with the campaign Diperlukan
`execution_options` list<enum{validate_only}>	Nilai default: `Set` An execution setting `validate_only`: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field. If the call passes validation or review, response will be `{"success": true}`. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

adlabels

list<Object>

Specification of ad labels to be associated with the campaign

Diperlukan

execution_options

list<enum{validate_only}>

Nilai default: Set

Jenis Pengembalian

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Error Codes

Kesalahan	Description
100	Invalid parameter

Menghapus

Examples

Deleting Labels:

Removing Existing Associations from an ad object:

You can delete an AdLabel by making a DELETE request to /{ad_label_id}.

Parameter

Titik akhir ini tidak memiliki parameter.

Jenis Pengembalian

Struct {

success: bool,

}

Error Codes

Kesalahan	Description
100	Invalid parameter