Apex Web サービス

たとえば、自社のコールセンターで内部アプリケーションを使用して、社内リソースを管理しているとします。カスタマーサポート担当者は、同じアプリケーションを使用して日常業務 (Salesforce のケースレコードの管理など) も行えるようになります。担当者は、1 つのインターフェースを使用して、ケースレコードの表示や更新を行ったり、内部リソースにアクセスしたりできます。アプリケーションは、Apex Web サービスクラスをコールして、Salesforce ケースレコードを管理します。

REST サービスとしてクラスを公開

Apex クラスを REST Web サービスとして使用できるようにすることは簡単です。クラスをグローバルクラス、メソッドをグローバル静的メソッドとして定義します。アノテーションをクラスおよびメソッドに追加します。たとえば、このサンプル Apex REST クラスでは 1 つのメソッドを使用します。getRecord メソッドは、カスタム REST API コールです。これは、@HttpGet アノテーションが付加されており、GET 要求で呼び出されます。

@RestResource(urlMapping='/Account/*')
global with sharing class MyRestResource {
    @HttpGet
    global static Account getRecord() {
        // Add your code
    }
}

ご覧のとおり、クラスには @RestResource(urlMapping='/Account/*') アノテーションが付加されています。Apex REST のベースエンドポイントは、https://yourInstance.salesforce.com/services/apexrest/ です。URL 対応付けがベースエンドポイントに追加されて、REST サービスのエンドポイントが形成されます。たとえば、このクラスの例の REST エンドポイントは https://yourInstance.salesforce.com/services/apexrest/ です。お客様の組織では、https://yourInstance.salesforce.com/services/apexrest/Account/* のようになります。

URL 対応付けでは大文字と小文字が区別され、ワイルドカード (*) を含めることができます。

global static として公開する各メソッドを定義し、HTTP メソッドと関連付けるアノテーションを追加します。次のアノテーションを使用できます。それぞれのアノテーションは、各 Apex クラスで 1 回のみ使用できます。

SOAP サービスとしてクラスを公開

Apex クラスを SOAP Web サービスとして使用できるようにすることは REST と同様に簡単です。クラスをグローバルクラスとして定義します。公開する各メソッドに webservice キーワードと static 定義修飾子を追加します。webservice キーワードを追加したメソッドにはグローバルアクセス権が付与されます。

たとえば、次に 1 つのメソッドがあるサンプルクラスを示します。getRecord メソッドは、取引先レコードを返すカスタム SOAP API コールです。

global with sharing class MySOAPWebService {
    webservice static Account getRecord(String id) {
        // Add your code
    }
}

外部アプリケーションは、クラス WSDL ファイルを使用して、カスタム Apex メソッドを Web サービス処理としてコールできます。[設定] の [Apex クラス] ページからアクセスするクラスの詳細ページで、クラスのこの WSDL を生成します。通常、WSDL ファイルをサードパーティ開発者に送信 (または自身で使用) して、Web サービスのインテグレーションを作成します。

プラットフォームセキュリティは、Salesforce の最重要事項であるため、Web サービスから認証が要求されます。外部アプリケーションは、Apex クラスの WSDL の他に Enterprise WSDL または Partner WSDL を使用してログイン機能を実現する必要があります。

PUT メソッドを使用したデータの更新

CaseManager クラスに追加した upsertCase メソッドは、PUT アクションを実装します。ここに記載されているこのメソッドは参照用です。このメソッドは組み込みの upsert Apex DML メソッドを使用し、ID 値を照合してケースレコード項目を作成または上書きします。ID がリクエストボディで送信された場合、その ID を使用してケースの sObject が入力されます。ID が送信されない場合は、ID を使用せずにケースの sObject が作成されます。入力されるケースの sObject で upsert メソッドが呼び出され、DML ステートメントで残りの作業が行われます。成功です。

@HttpPut
global static ID upsertCase(String subject, String status,
    String origin, String priority, String id) {
    Case thisCase = new Case(
        Id=id,
        Subject=subject,
        Status=status,
        Origin=origin,
        Priority=priority);
    // Match case by Id, if present.
    // Otherwise, create new case.
    upsert thisCase;
    // Return the case ID.
    return thisCase.Id;
}

PATCH メソッドを使用したデータの更新

PUT メソッドの代わりに PATCH メソッド使用してレコード項目を更新できます。PATCH メソッドはさまざまな方法で実装できます。その方法の 1 つが、メソッドでパラメータを指定して各項目を更新することです。たとえば、updateCasePriority(String priority) という署名を使用して、ケースの優先度を更新するメソッドを作成できます。複数の項目を更新するには、目的のすべての項目をパラメータとしてリストします。

または、リクエストボディで項目を JSON の名前/値ペアとして渡します。後者の方が柔軟性が高くなります。こうすることで、メソッドは任意の数のパラメータを受け入れることができ、パラメータがメソッドの署名で固定されなくなります。この方法には、null になることが原因で誤って項目がクリアされることがないという利点もあります。CaseManager クラスに追加した updateCaseFields メソッドは、この 2 番目の方法を使用します。この方法では、リクエストボディの JSON 文字列を名前/値ペアの対応付けに並列化し、sObject PUT メソッドを使用して項目を設定します。

@HttpPatch
global static ID updateCaseFields() {
    RestRequest request = RestContext.request;
    String caseId = request.requestURI.substring(
        request.requestURI.lastIndexOf('/')+1);
    Case thisCase = [SELECT Id FROM Case WHERE Id = :caseId];
    // Deserialize the JSON string into name-value pairs
    Map<String, Object> params = (Map<String, Object>)JSON.deserializeUntyped(request.requestbody.tostring());
    // Iterate through each parameter field and value
    for(String fieldName : params.keySet()) {
        // Set the field and value on the Case sObject
        thisCase.put(fieldName, params.get(fieldName));
    }
    update thisCase;
    return thisCase.Id;
}

次に、Apex REST サービスをテストする一般的な方法を示します。REST 要求をシミュレーションするには、次のようにテストメソッドで RestRequest を作成し、要求のプロパティを設定します。また、要求で「渡す」パラメータを追加して URI パラメータをシミュレーションすることもできます。

// Set up a test request
RestRequest request = new RestRequest();

// Set request properties
request.requestUri =
    'https://yourInstance.salesforce.com/services/apexrest/Cases/'
    + recordId;
request.httpMethod = 'GET';

// Set other properties, such as parameters
request.params.put('status', 'Working');

// more awesome code here....
// Finally, assign the request to RestContext if used
RestContext.request = request;

テストするメソッドが RestContext を介して要求値にアクセスする場合、要求を RestContext に割り当てて、要求 (RestContext.request = request;) を入力します。

次に、開発者コンソールでクラス全体を保存し、結果を実行します。

1. 開発者コンソールで、[File (ファイル)] | [New (新規)] | [Apex Class (Apex クラス)] を選択します。
2. クラス名として「CaseManagerTest」と入力し、[OK] をクリックします。
3. 自動生成されるコードを次のクラス定義で置き換えます。

   @IsTest
   private class CaseManagerTest {
   
       @isTest static void testGetCaseById() {
           Id recordId = createTestRecord();
           // Set up a test request
           RestRequest request = new RestRequest();
           request.requestUri =
               'https://yourInstance.salesforce.com/services/apexrest/Cases/'
               + recordId;
           request.httpMethod = 'GET';
           RestContext.request = request;
           // Call the method to test
           Case thisCase = CaseManager.getCaseById();
           // Verify results
           System.assert(thisCase != null);
           System.assertEquals('Test record', thisCase.Subject);
       }
   
       @isTest static void testCreateCase() {
           // Call the method to test
           ID thisCaseId = CaseManager.createCase(
               'Ferocious chipmunk', 'New', 'Phone', 'Low');
           // Verify results
           System.assert(thisCaseId != null);
           Case thisCase = [SELECT Id,Subject FROM Case WHERE Id=:thisCaseId];
           System.assert(thisCase != null);
           System.assertEquals(thisCase.Subject, 'Ferocious chipmunk');
       }
   
       @isTest static void testDeleteCase() {
           Id recordId = createTestRecord();
           // Set up a test request
           RestRequest request = new RestRequest();
           request.requestUri =
               'https://yourInstance.salesforce.com/services/apexrest/Cases/'
               + recordId;
           request.httpMethod = 'GET';
           RestContext.request = request;
           // Call the method to test
           CaseManager.deleteCase();
           // Verify record is deleted
           List<Case> cases = [SELECT Id FROM Case WHERE Id=:recordId];
           System.assert(cases.size() == 0);
       }
   
       @isTest static void testUpsertCase() {
           // 1. Insert new record
           ID case1Id = CaseManager.upsertCase(
                   'Ferocious chipmunk', 'New', 'Phone', 'Low', null);
           // Verify new record was created
           System.assert(Case1Id != null);
           Case case1 = [SELECT Id,Subject FROM Case WHERE Id=:case1Id];
           System.assert(case1 != null);
           System.assertEquals(case1.Subject, 'Ferocious chipmunk');
           // 2. Update status of existing record to Working
           ID case2Id = CaseManager.upsertCase(
                   'Ferocious chipmunk', 'Working', 'Phone', 'Low', case1Id);
           // Verify record was updated
           System.assertEquals(case1Id, case2Id);
           Case case2 = [SELECT Id,Status FROM Case WHERE Id=:case2Id];
           System.assert(case2 != null);
           System.assertEquals(case2.Status, 'Working');
       }    
   
       @isTest static void testUpdateCaseFields() {
           Id recordId = createTestRecord();
           RestRequest request = new RestRequest();
           request.requestUri =
               'https://yourInstance.salesforce.com/services/apexrest/Cases/'
               + recordId;
           request.httpMethod = 'PATCH';
           request.addHeader('Content-Type', 'application/json');
           request.requestBody = Blob.valueOf('{"status": "Working"}');
           RestContext.request = request;
           // Update status of existing record to Working
           ID thisCaseId = CaseManager.updateCaseFields();
           // Verify record was updated
           System.assert(thisCaseId != null);
           Case thisCase = [SELECT Id,Status FROM Case WHERE Id=:thisCaseId];
           System.assert(thisCase != null);
           System.assertEquals(thisCase.Status, 'Working');
       }  
   
       // Helper method
       static Id createTestRecord() {
           // Create test record
           Case caseTest = new Case(
               Subject='Test record',
               Status='New',
               Origin='Phone',
               Priority='Medium');
           insert caseTest;
           return caseTest.Id;
       }          
   
   }

4. CTRL+S キーを押して保存します。
5. [Test (テスト)] | [Run All (すべて実行)] を選択して、組織のすべてのテストを実行します。

[Tests (テスト)] タブにテスト結果が表示されます。テスト実行が完了したら、[Overall Code Coverage (全体のコードカバー率)] ペインで CaseManager 行を確認します。カバー率が 100% になっています。

Apex REST でサポートされているデータ型

Apex REST では、パラメータおよび戻り値で次のデータ型がサポートされています。

• Apex プリミティブ (sObject と Blob を除く)。
• sObject
• Apex プリミティブまたは sObject のリストまたは対応付け (String キーの対応付けのみをサポート)。
• 上記の型のメンバー変数を含むユーザ定義型。

Apex REST エンドポイントの名前空間

Apex REST メソッドは、管理パッケージと未管理パッケージで使用できます。管理パッケージに含まれる Apex REST メソッドをコールする場合、REST のコール URL に管理パッケージの名前空間を含める必要があります。たとえば、packageNamespace という管理パッケージ名前空間にクラスが含まれており、Apex REST メソッドが /MyMethod/* という URL 対応付けを使用している場合、これらのメソッドをコールするために REST によって使用される URL は、https://instance.salesforce.com/services/apexrest/packageNamespace/MyMethod/ という形式になります。

カスタム Apex Web サービスと Salesforce API

REST および SOAP サービスのカスタム Apex コードを使用する代わりに、Salesforce の REST および SOAP API を使用して、外部アプリケーションを Salesforce と統合できます。これらの API では、レコードの作成、更新、削除ができます。ただし、Apex Web サービスを使用する利点は、Apex メソッドで複雑なロジックをカプセル化できることです。このロジックは、消費アプリケーションから隠ぺいされます。また、クライアントと Salesforce サーバ間で実行される往復処理が少なくなるため、Apex クラスの処理が個々の API コールを実行するよりも高速になる可能性があります。Apex Web サービスコールでは、1 つの要求のみが送信され、メソッド内の処理はすべてサーバで実行されます。

Apex Web サービスのセキュリティに関する考慮事項

Apex Web サービスメソッドが実行されるセキュリティコンテキストは、Salesforce API のセキュリティコンテキストとは異なります。Salesforce API とは異なり、Apex Web サービスメソッドはシステム権限で実行され、ユーザのオブジェクト権限や項目権限は考慮されません。ただし、Apex Web サービスメソッドが with sharing キーワードで宣言されている場合は、共有ルールが適用されます。