تنفيذ عروض الأسعار المخصصة

تتيح لك واجهة برمجة التطبيقات Display & Video 360 API إدارة عمليات تنفيذ عروض الأسعار المخصّصة بالكامل. يمكنك إنشاء خوارزميات عروض أسعار مخصّصة وتحميل ملفّات برمجية فردية والتحقّق منها وتحديد خوارزمية معيّنة لمورد معيّن كاستراتيجية عروض أسعاره.

توضّح هذه الصفحة كيفية إنشاء خوارزميات عروض الأسعار المخصّصة وتعديلها وتحديدها باستخدام واجهة برمجة التطبيقات في "مساحة العرض والفيديو 360". يقدّم كل قسم نموذجًا للرمز.

إنشاء خوارزمية عروض أسعار مخصّصة

يمثّل عنصر CustomBiddingAlgorithm خوارزمية individual يمكنك تعيينها إلى عنصر لاستعمالها في استراتيجية عروض أسعاره. يحتوي هذا العنصر على تفاصيل عن الخوارزمية، مثل customBiddingAlgorithmType و entityStatus، بالإضافة إلى readinessState وsuspensionState لكلّ نموذج تم إنشاؤه من قِبل المعلِن ذي الصلة. يمكنك إنشاء كائنَي CustomBiddingScript و CustomBiddingAlgorithmRules كمصادر فرعية لاستخدامها في الخوارزمية.

في ما يلي مثال على كيفية إنشاء خوارزمية عروض أسعار مخصّصة مستندة إلى نصّ برمجي:

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithm customBiddingAlgorithm =
    new CustomBiddingAlgorithm()
        .setAdvertiserId(advertiser-id)
        .setDisplayName(display-name)
        .setEntityStatus("ENTITY_STATUS_ACTIVE")
        .setCustomBiddingAlgorithmType("SCRIPT_BASED");

// Configure the create request.
CustomBiddingAlgorithms.Create request =
    service.customBiddingAlgorithms().create(customBiddingAlgorithm);

// Create the custom bidding algorithm.
CustomBiddingAlgorithm response = request.execute();

// Display the new custom bidding algorithm name.
System.out.printf(
    "Custom bidding algorithm %s was created.%n",
    response.getName()
);

Python

# Create a custom bidding algorithm object.
custom_bidding_algorithm_obj = {
    'advertiserId': advertiser-id,
    'displayName': display-name,
    'entityStatus': 'ENTITY_STATUS_ACTIVE',
    'customBiddingAlgorithmType': 'SCRIPT_BASED'
}

# Create the custom bidding algorithm.
response = service.customBiddingAlgorithms().create(
    body=custom_bidding_algorithm_obj
).execute()

# Display the new custom bidding algorithm.
print(f'The following Custom Bidding Algorithm was created: {response}')

PHP

// Create a custom bidding algorithm object.
$customBiddingAlgorithm =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithm();
$customBiddingAlgorithm->setAdvertiserId(advertiser-id);
$customBiddingAlgorithm->setDisplayName(display-name);
$customBiddingAlgorithm->setEntityStatus('ENTITY_STATUS_ACTIVE');
$customBiddingAlgorithm->setCustomBiddingAlgorithmType('SCRIPT_BASED');

// Create the custom bidding algorithm.
$result =
    $this->service->customBiddingAlgorithms->create($customBiddingAlgorithm);

// Display the new custom bidding algorithm name.
printf('Custom Bidding Algorithm %s was created.\n', $result['name']);

إدارة أذونات الوصول إلى الخوارزميات

يمكن أن تكون خوارزميات عروض الأسعار المخصّصة مملوكة لشريك أو معلِن. يمكن للشريك ولأي معلِنين تابعين له والمدرَجين في الحقل sharedAdvertiserIds الوصول إلى الخوارزميات التي يملكها الشريك وتعديلها. يمكن للمعلِن وشريكه الرئيسي الوصول إلى الخوارزميات التي يملكها المعلِن وتعديلها، ولكن لا يمكن مشاركتها مع المعلِنين الآخرين.

إذا كنت تستخدِم الخوارزمية لمعلِن واحد فقط، حدِّد المعلن على أنّه المالك باستخدام الحقل advertiserId. بخلاف ذلك، يمكنك منح الشريك الرئيسي للمعلنين دور المالك باستخدام الحقل partnerId، ومنح المعلنين إذن الوصول باستخدام الحقل sharedAdvertiserIds.

تحميل منطق الخوارزمية

استنادًا إلى نوع خوارزمية عروض الأسعار المخصّصة، عليك بعد ذلك إنشاء إما نص برمجي أو عنصر قواعد يمكنك فيه تقديم المنطق الذي ستستخدمه الخوارزمية.

تحميل نص

تستخدِم خوارزميات عروض الأسعار المخصّصة المستندة إلى النصوص النصوص المقدَّمة من المستخدِم لتقييم قيمة مرّة الظهور. تتوفّر نماذج من النصوص البرمجية البسيطة وقائمة ب الحقول المتقدّمة من خلال مركز مساعدة "مساحة العرض والفيديو 360".

توضّح لك الأقسام التالية كيفية إضافة نص برمجي جديد أو معدّل إلى خوارزمية bidding سفارشية.

استرداد موقع مرجع نص برمجي

أولاً، استردّ موقعًا جغرافيًا متاحًا للمورد ضمن مورد أسلوب bidding المخصّص باستخدام الأسلوب customBiddingAlgorithms.uploadScript. يعرِض هذا الطلب عنصر CustomBiddingScriptRef يتضمّن اسم مورد. يمكنك تحميل ملف النص البرمجي إلى الموقع الذي يحدّده اسم المورد. بعد ذلك، استخدِم عنصر مرجع نص عروض الأسعار المخصّصة لإنشاء مرجع نصك.

في ما يلي مثال على كيفية استرداد موقع مورد متاح:

Java

// Retrieve a usable custom bidding script
// reference.
CustomBiddingScriptRef scriptRef =
    service
        .customBiddingAlgorithms()
        .uploadScript(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the custom bidding script reference resource path.
System.out.printf(
    "The script can be uploaded to the following resource path: %s%n",
    scriptRef.getResourceName()
);

Python

# Retrieve a usable custom bidding script reference
# object.
custom_bidding_script_ref = service.customBiddingAlgorithms().uploadScript(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding script reference object.
print('The following custom bidding script reference object was retrieved:'
      f'{custom_bidding_script_ref}')

PHP

// Set parent advertiser ID of custom bidding
// algorithm in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding script reference.
$scriptRefResponse = $this->service->customBiddingAlgorithms->uploadScript(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding script reference object.
printf(
    'The script can be uploaded to the following resource path: %s\n',
    $scriptRefResponse->getResourceName()
);

تحميل ملف نص برمجي

بعد استرداد موقع مورد متاح، حمِّل ملف النص البرمجي إلى ذلك الموقع في نظام "مساحة العرض والفيديو 360" باستخدام الأسلوب media.upload. تتيح هذه الطريقة تحميلًا بسيطًا يتطلّب مَعلمة طلب البحث uploadType=media.

في ما يلي مثال على كيفية تحميل ملف نصّي استنادًا إلى عنصر مرجعي مخصّص لملف نصّ برمجي لعروض الأسعار تم استرجاعه:

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the script file.
InputStreamContent scriptFileStream =
    new InputStreamContent(
        null, new FileInputStream(script-path));

// Create media.upload request.
Media.Upload uploadRequest =
        service
            .media()
            .upload(
                resource-name,
                media,
                scriptFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

Python

# Create a media upload object.
media = MediaFileUpload(script-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload script to resource location given in retrieved custom bidding
# script reference object.
upload_request.execute()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(script-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload script file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @script-path

إنشاء عنصر نص برمجي

بعد تحميل ملف النص البرمجي، أنشئ مورد نص برمجي مخصّصًا لعروض الأسعار باستخدام customBiddingAlgorithms.scripts.create. يجب أن يتضمّن عنصر CustomBiddingScript الذي تم تمريره في الطلب CustomBiddingScriptRef فقط كقيمة المخصّصة للحقل script. يؤدي ذلك إلى ربط ملف الرمز البرمجي الذي تم تحميله بمصدر النص البرمجي الجديد.

في ما يلي مثال على كيفية إنشاء مورد نص برمجي:

Java

// Create the custom bidding script structure.
CustomBiddingScript customBiddingScript =
    new CustomBiddingScript()
        .setScript(custom-bidding-script-ref);

// Create the custom bidding script.
CustomBiddingScript response =
    service
        .customBiddingAlgorithms()
        .scripts()
        .create(custom-bidding-algorithm-id, customBiddingScript)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new script resource name
System.out.printf(
    "The following script was created: %s%n",
    response.getName());

Python

# Create a custom bidding script object.
script_obj = {
    'script': custom-bidding-script-ref
}

# Create the custom bidding script.
response = service.customBiddingAlgorithms().scripts().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=script_obj).execute()

# Display the new custom bidding script object.
print(f'The following custom bidding script was created: {response}')

PHP

// Create the custom bidding script object.
$customBiddingScript =
    new Google_Service_DisplayVideo_CustomBiddingScript();
$customBiddingScript->setScript(custom-bidding-script-ref);

// Set parameters for create script request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding script.
$result = $this->service->customBiddingAlgorithms_scripts->create(
    custom-bidding-algorithm-id,
    $customBiddingScript,
    $optParams
);

// Display the new script resource name.
printf('The following script was created: %s.\n', $result->getName());

بعد إنشاء مورد نص برمجي لعروض الأسعار المخصّصة، تعالج "مساحة العرض والفيديو 360" النص البرمجي للتأكّد من إمكانية استخدامه بنجاح لتسجيل مرّات الظهور. يمكنك استرداد حالة هذه المعالجة من خلال حقل state الخاص بكائن النص البرمجي. بعد قبول النص البرمجي الجديد، تبدأ خوارزمية bidding المخصّصة باستخدام النص البرمجي لتقييم قيم مرّات الظهور. يحدث ذلك على الفور، لذا تأكَّد من أنّك تريد تعديل الخوارزمية قبل إنشاء مرجع نص برمجي جديد.

قواعد التحميل

تستخدِم خوارزميات عروض الأسعار المخصّصة المستندة إلى القواعد منطقًا مقدَّمًا في عنصر AlgorithmRules لتقييم قيمة مرّة الظهور.

يتم تحميل عناصر AlgorithmRules في ملف JSON ثم يتم ربطها بآلية عروض أسعار مخصّصة من خلال عنصر CustomBiddingAlgorithmRules.

استرداد موقع مورد القواعد

أولاً، استردّ موقعًا جغرافيًا متاحًا للمورد ضمن مورد أسلوب bidding المخصّص باستخدام الأسلوب customBiddingAlgorithms.uploadRules. يعرض هذا الطلب عنصر CustomBiddingAlgorithmsRulesRef مع اسم مورد. يمكنك تحميل ملف القواعد إلى الموقع الذي يحدّده اسم المورد. بعد ذلك، استخدِم عنصر مرجع قواعد خوارزمية عروض الأسعار المخصّصة لإنشاء موارد قواعدك.

في ما يلي مثال على كيفية استرداد موقع مورد متاح:

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithmRulesRef rulesRef =
    service
        .customBiddingAlgorithms()
        .uploadRules(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

System.out.printf(
    "The rules can be uploaded to the following resource path: %s%n",
    rulesRef.getResourceName()
);

Python

# Retrieve a usable custom bidding algorithm rules reference
# object.
custom_bidding_algorithm_rules_ref = service.customBiddingAlgorithms().uploadRules(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding algorithm rules reference object.
print('The following custom bidding algorithm rules reference object was retrieved:'
      f' {custom_bidding_algorithm_rules_ref}')

PHP

// Set parent advertiser ID of custom bidding algorithm
// in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding algorithm rules reference.
$rulesRefResponse = $this->service->customBiddingAlgorithms->uploadRules(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding algorithm rules reference object resource path.
printf(
    'The rules can be uploaded to the following resource path: %s\n',
    $rulesRefResponse->getResourceName()
);

تحميل ملف AlgorithmRules

بعد استرداد موقع مرجع متاح، حمِّل ملف القواعد إلى ذلك الموقع في نظام "مساحة العرض والفيديو 360" باستخدام media.upload. تتيح هذه الطريقة تحميلًا بسيطًا يتطلّب مَعلمة طلب البحث uploadType=media.

في ما يلي مثال على كيفية تحميل ملف AlgorithmRules استنادًا إلى عنصر مرجعي تم استرجاعه لقواعد خوارزمية عروض الأسعار المخصّصة:

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the rules file.
InputStreamContent rulesFileStream =
    new InputStreamContent(
        null, new FileInputStream(rules-file-path));

// Create media.upload request.
 Media.Upload uploadRequest =
    service
        .media()
        .upload(
            resource-name,
            media,
            rulesFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

Python

# Create a media upload object.
media = MediaFileUpload(rules-file-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload rules file to resource location given in retrieved custom bidding
# algorithm rules reference object.
upload_request.execute()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(rules-file-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload rules file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @rules-file-path

إنشاء عنصر قواعد

بعد تحميل ملف JSON بتنسيق AlgorithmRules، أنشئ مرجعًا مخصّصًا لقواعد أسلوب تسعير bidding باستخدام الطريقة customBiddingAlgorithms.rules.create. يجب أن يتضمّن كائن CustomBiddingAlgorithmRules الذي تم تمريره في الطلب فقط كائن CustomBiddingAlgorithmRulesRef كأحد القيم المحدّدة للحقل rules. يؤدي ذلك إلى ربط ملف AlgorithmRules JSON المحمَّل بمصدر القواعد الجديد.

في ما يلي مثال على كيفية إنشاء مورد قواعد:

Java

// Create the custom bidding algorithm rules structure.
CustomBiddingAlgorithmRules customBiddingAlgorithmRules =
    new CustomBiddingAlgorithmRules()
        .setRules(custom-bidding-algorithm-rules-ref);

// Create the rules resource.
CustomBiddingAlgorithmRules response =
    service
        .customBiddingAlgorithms()
        .rules()
        .create(custom-bidding-algorithm-id, customBiddingAlgorithmRules)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new rules resource name.
System.out.printf(
    "The following custom bidding algorithm rules object was created: %s%n",
    response.getName());

Python

# Create the custom bidding algorithm rules object.
rules_obj = {
    'rules': custom-bidding-algorithm-rules-ref
}

# Create the rules resource.
response = service.customBiddingAlgorithms().rules().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=rules_obj).execute()

# Display the new custom bidding algorithm rules object.
print(f'The following custom bidding algorithm rules resource was created: {response}')

PHP

// Create the custom bidding algorithm rules object.
$customBiddingAlgorithmRules =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithmRules();
$customBiddingAlgorithmRules->setRules(custom-bidding-algorithm-rules-ref);

// Set parameters for create rules request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding algorithm rules resource.
$result = $this->service->customBiddingAlgorithms_rules->create(
    custom-bidding-algorithm-id,
    $customBiddingAlgorithmRules,
    $optParams
);

// Display the new custom bidding algorithm rules resource name.
printf('The following rules resource was created: %s.\n', $result->getName());

بعد إنشاء مورد قواعد، تعالج "مساحة العرض والفيديو 360" مجموعة القواعد للتأكّد من إمكانية استخدامها بنجاح لتسجيل مرّات الظهور. يمكنك استرداد حالة هذه المعالجة من خلال حقل state لكائن القواعد. بعد قبول القواعد الجديدة، تبدأ خوارزمية عروض الأسعار المخصّصة في استخدام القواعد لتقييم قيم مرّات الظهور على الفور.

إذا تم رفض القواعد، يمكنك استرداد سبب الرفض من error القواعد العنصر. في حال الرفض، عدِّل AlgorithmRules لإصلاح الخطأ وكرِّر عملية التحميل بدءًا من استرداد عنصر مرجع القواعد.

منح خوارزمية عروض أسعار مخصّصة

بعد إنشاء خوارزمية عروض أسعار مخصّصة وتحميل المنطق المقبول واستيفاء المتطلبات اللازمة، يمكنك تعيين خوارزمية عروض الأسعار المخصّصة لاستراتيجية عروض أسعار عنصر أو طلب إدراج.

يمكنك استخدام خوارزميات عروض الأسعار المخصّصة في استراتيجيتَي عروض الأسعار تحقيق الحد الأقصى من الإنفاق و هدف الأداء من خلال منح القيمة BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO ورقم تعريف خوارزمية عروض الأسعار المخصّصة للحقول performanceGoalType و customBiddingAlgorithmId، على التوالي. استنادًا إلى استراتيجية عروض الأسعار، قد تكون مَعلمات عروض أسعار أخرى متاحة أو مطلوبة.

في ما يلي مثال على كيفية تعديل عنصر ليكون ضمن استراتيجية عروض أسعار تهدف إلى زيادة الإنفاق مع خوارزمية عروض أسعار مخصّصة معيّنة:

Java

// Create the line item structure.
LineItem lineItem = new LineItem();

// Create and set the bidding strategy structure.
BiddingStrategy biddingStrategy = new BiddingStrategy();
MaximizeSpendBidStrategy maxSpendBidStrategy =
    new MaximizeSpendBidStrategy()
        .setPerformanceGoalType(
            "BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO")
        .setCustomBiddingAlgorithmId(custom-bidding-algorithm-id);
biddingStrategy.setMaximizeSpendAutoBid(maxSpendBidStrategy);
lineItem.setBidStrategy(biddingStrategy);

// Configure the patch request and set update mask to only update
// the bid strategy.
LineItems.Patch request =
    service
        .advertisers()
        .lineItems()
        .patch(advertiser-id, line-item-id, lineItem)
        .setUpdateMask("bidStrategy");

// Update the line item.
LineItem response = request.execute();

// Display the custom bidding algorithm ID used in the new
// bid strategy.
System.out.printf(
    "LineItem %s now has a bid strategy utilizing custom "
        + "bidding algorithm %s%n",
    response.getName(),
    response
        .getBidStrategy()
        .getMaximizeSpendAutoBid()
        .getCustomBiddingAlgorithmId());

Python

# Create the new bid strategy object.
bidding_strategy = {
    'maximizeSpendAutoBid': {
        'performanceGoalType':
            'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO',
        'customBiddingAlgorithmId': custom-bidding-algorithm-id
    }
}

# Create a line item object assigning the new bid strategy.
line_item_obj = {'bidStrategy': bidding_strategy}

# Update the line item with a new bid strategy.
response = service.advertisers().lineItems().patch(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    updateMask='bidStrategy',
    body=line_item_obj).execute()

# Display the line item's new bid strategy
print(f'Line Item {response["name"]} is now using the following bid'
     f' strategy: {response["bidStrategy"]}.')

PHP

// Create the line item structure.
$lineItem = new Google_Service_DisplayVideo_LineItem();

// Create and set the bidding strategy structure.
$biddingStrategy =  new Google_Service_DisplayVideo_BiddingStrategy();
$maximizeSpendBidStrategy =
    new Google_Service_DisplayVideo_MaximizeSpendBidStrategy();
$maximizeSpendBidStrategy->setPerformanceGoalType(
    'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO'
);
$maximizeSpendBidStrategy->setCustomBiddingAlgorithmId(
    custom-bidding-algorithm-id
);
$biddingStrategy->setMaximizeSpendAutoBid($maximizeSpendBidStrategy);
$lineItem->setBidStrategy($biddingStrategy);

// Set update mask.
$optParams = array('updateMask' => 'bidStrategy');

// Update the line item.
$result = $this->service->advertisers_lineItems->patch(
    advertiser-id,
    line-item-id,
    $lineItem,
    $optParams
);

// Display the custom bidding algorithm ID used in the new bid strategy.
printf(
    'Line Item %s now has a bid strategy utilizing custom bidding algorithm %s.\n',
    $result['name'],
    $result['bidStrategy']['maximizeSpendBidStrategy']['customBiddingAlgorithmId']
);