AttachmentCreator SOAP Web サービス

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：13分

    • ecc_queue テーブルを対象とする SOAP メッセージを送信して、ServiceNow のレコードにドキュメントを添付します。

    重要:
    AttachmentCreator SOAP Web サービスは推奨されません。代わりに、REST 添付ファイル API を使用して Web サービスの添付ファイルを管理します。
    AttachmentCreator SOAP Web サービスを使用すると、1 つのメッセージに最大 5 MB の 1 つのドキュメントを添付できます。URL またはターゲットエンドポイントの例を次に示します。https://instance_name.service-now.com/ecc_queue.do?WSDL
    表 : 1. 添付ファイルを作成するための ecc_queue フィールド
    フィールド名 説明 値
    agent 要求を送信するエージェントの名前。処理に使用されないため、任意の値を使用できます。 AttachmentCreator
    topic キューレコードのトピック。添付ファイルの作成をトリガーするには、この値を「AttachmentCreator」に設定する必要があります AttachmentCreator
    name このフィールドには、「:」で区切られたファイル名の値とそのコンテンツタイプを含める必要があります file_name.xls:application/vnd.ms-excel
    source このフィールドには、「:」で区切られたターゲットテーブルの値とその sys_id を含める必要があります。 incident:dd90c5d70a0a0b39000aac5aee704ae8
    payload このフィールドには、添付するオブジェクトを表す Base 64 でエンコードされた文字列を含める必要があります。 Base 64 でエンコードされた文字列

    上の表に記載されている値を送信すると、sys_id dd90c5d70a0a0b39000aac5aee704ae8 で特定されたレコードのインシデントテーブルに Excel ファイルが添付されます。

    セキュリティ

    プラットフォームで利用可能な他のすべての HTTP ベースの Web サービスと同様に、AttachementCreator SOAP Web サービスは、デフォルトで基本認証を使用して認証する必要があります。認証に使用されるユーザー ID は、インタラクティブユーザーと同じ方法でアクセス制御されます。

    添付ファイルを作成するには、添付ファイル [sys_attachment] レコードを作成するために必要なロールと soap_create ロール、およびターゲット テーブルでレコードを読み書きするために必要なロール (添付ファイルをインシデントレコードに追加する itil ロールなど) を SOAP ユーザーが持っている必要があります。デフォルトでは、添付ファイルを追加できる単一のロールはありません。添付ファイルの追加を明示的に許可するロールを作成し、このロールを SOAP ユーザーに割り当てることができます。

    ファイルタイプのセキュリティ

    glide.attachment.extensions および glide.security.file.mime_type.validation プロパティを設定することで、ユーザーが添付できるファイルタイプを制御できます。

    これらのプロパティを AttachmentCreator Web サービスに適用するには、プロパティ glide.attachment.enforce_security_validation を true に設定する必要があります。このプロパティはデフォルトで true です。

    SOAP メッセージの例

    次に示すのは、MIME タイプが text/plain のテキストファイル「john1.txt」を取得し、それを GUID が e6eed6950a0a3c59006f32c8e3ff3cf9 であるインシデントに添付する SOAP メッセージの例です。ペイロードはファイル自体の base64 エンコードであることに注意してください。
    <?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ecc="http://www.service-now.com/ecc_queue">
    <soapenv:Header />
    <soapenv:Body>
        <ecc:insert>
            <agent>AttachmentCreator</agent>
            <topic>AttachmentCreator</topic>
            <name>john1.txt:text/plain</name>
            <source>incident:e6eed6950a0a3c59006f32c8e3ff3cf9</source>
            <payload>SSB3b25kZXIgaWYgc2hlIGtub3ducyB3aGF0IHNoZSdzIGRvaW5nIG5vdy4K</payload>
        </ecc:insert>
    </soapenv:Body>
</soapenv:Envelope>

    Node.js スクリプトの例

    次の例の Node.js スクリプトは、添付ファイルをインシデントレコードに追加します。このスクリプトを、インスタンスではなくクライアントコンピューターから実行します。
    /**
 * 
 * Node.js to ServiceNow attachment upload via SOAP
 * 
 * Andrew Venables andrew.venables@servicenow.com
 * July 2014
 * 
 * Version 1.0
 * 
 */

var soap = require('soap'), // https://github.com/vpulim/node-soap
	mime = require('mime'), // https://github.com/broofa/node-mime
	fs = require("fs");

var WSDL_FILENAME = 'ecc_queue.xml'; // Goto https://instancename.service-now.com/ecc_queue.do?WSDL and save a copy of the WSDL locally for simplicity
var DIRECTORY_CONTAINING_FILES = '/Users/andrew.venables/Documents/Uploads'; // Local path to the directory containing all the files we want to upload
var USERNAME = 'andy.venables'; // An admin user account on the instance
var PASSWORD = 'MY_PASSWORD'; // Password for above account
var TARGET_TABLE = 'incident'; // Target table to attach the files to
var TARGET_SYS_ID = '9d385017c611228701d22104cc95c371'; // Target record / sys_id to attach the files to. OOTB INC0000002

var files_to_upload; // Global that will contain our list of files to be uploaded
var pos = 0; // Global pointer for our position in the files_to_upload list

// Create a SOAP client to use to post to the instance
soap.createClient(WSDL_FILENAME, function(err, client) { // Node uses callbacks
	if (err) console.error(err);
	
	// Set the username and password
	client.setSecurity(new soap.BasicAuthSecurity(USERNAME, PASSWORD));
	
	// Read all the files in our source directory, will include . and ..
	files_to_upload = fs.readdirSync(DIRECTORY_CONTAINING_FILES);
	
	console.log('Files to upload: ' + files_to_upload.length + '\n');
	
	// Start iterating through the list of files to upload
	next(client);
		
});

// Process the next file in the files_to_upload array
// This is a neat way of dealing with Node and its expectation of callbacks
function next(client) {
	
	// Check we haven't reached the end
	if (pos >= files_to_upload.length) return;
	
	// Get the next file to upload
	var file_name = files_to_upload[pos];
	
	// Increment the pointer to the next file
	pos++;
	
	console.log(pos + '/'+ files_to_upload.length+ ' - Uploading file: ' + file_name);

	// A blank file is the end of the list
	if (file_name == '') return;
	
	// Skip to the next file as this one is invalid
	if (file_name == '.' || file_name == '..' || file_name.indexOf('.') == 0) 
		next(client);
	
	// Get the file type using an module called mime
	var file_type = mime.lookup(file_name);
	console.log('   of type: ' + file_type);
	
	var file_payload;
	// Load the file into a buffer
	fs.readFile(DIRECTORY_CONTAINING_FILES + '/' + file_name, function(err, the_data) {
		if (err) console.error(err);
		
		// Encode the buffer to base64
		file_payload = new Buffer(the_data, 'binary').toString('base64');
		
		// Set the parameters before we call the Web Service
		var parameters = {
			'agent': 	'AttachmentCreator',
	        'topic': 	'AttachmentCreator',
	        'name': 	file_name+':'+file_type,
	        'source': 	TARGET_TABLE+':'+TARGET_SYS_ID,
	        'payload': 	file_payload
		};
		
		console.log('      sending...')
		// Make the Web Service call, remember node likes callbacks
		client.insert(parameters, function(err, result) {
			if (err) console.error(err);
			
			console.log(result);
			
			// This file is done, next!
			next(client);
		});
	});
}

    Perl スクリプトの例

    次の例の Perl スクリプトは、添付ファイルをインシデントレコードに作成します。
    use MIME::Base64;
use strict;
use SOAP::Lite;
 
# the ServiceNow instance
my $SNC_HOST = "https://instance_name.service-now.com";
my $base64;
my $buf;
 
# upload and attach a file on the local disk, base 64 encode it into a string first
open(FILE, "/Users/davidloo/Desktop/test_files/number_test.xls") or die "$!";
binmode FILE; #preserves file formatting on Windows
while (read(FILE, $buf, 60*57)) {
  $base64 .= encode_base64($buf);
}
 
# call the sub routine to attach
attach_incident();
 
sub attach_incident {
  # target the ecc_queue table
  my $soap = SOAP::Lite->proxy("$SNC_HOST/ecc_queue.do?SOAP");
  $soap->{_transport}->{_proxy}->{ssl_opts}->{verify_hostname} = 0;
  my $method = SOAP::Data->name('insert')->attr({xmlns => 'http://www.service-now.com/'});
 
  # set the ecc_queue parameters
  my @params = (SOAP::Data->name(agent => 'AttachmentCreator'));
  push(@params, SOAP::Data->name(topic => 'AttachmentCreator') );
 
  # identify the file name and its mime type
  push(@params, SOAP::Data->name(name => 'number_test.xls:application/vnd.ms-excel') );
 
  # attach to the incident, specifying its sys_id
  push(@params, SOAP::Data->name(source => 'incident:dd90c5d70a0a0b39000aac5aee704ae8') );
 
  # set the payload to be the base 64 encoded string representation of the file
  push(@params, SOAP::Data->name(payload => $base64) );
 
  # invoke the web service
  my $result = $soap->call($method => @params);
 
  print_fault($result);
 
  print_result($result);
}
 
sub print_result {
  my ($result) = @_;
 
  if ($result->body && $result->body->{'insertResponse'}) {
    my %keyHash = %{ $result->body->{'insertResponse'} };
    foreach my $k (keys %keyHash) {
        print "name=$k   value=$keyHash{$k}\n";
    }
  }
}
 
sub print_fault {
  my ($result) = @_;
 
  if ($result->fault) {
    print "faultcode=" . $result->fault->{'faultcode'} . "\n";
    print "faultstring=" . $result->fault->{'faultstring'} . "\n";
    print "detail=" . $result->fault->{'detail'} . "\n";
  }
}
 
# use the itil user for basic auth credentials
sub SOAP::Transport::HTTP::Client::get_basic_credentials {
   return 'itil' => 'itil';
}